Filters are true/false conditions about players, blocks, or the match in general. Other modules use filters to decide if and when things should happen to those players, blocks, or the entire match.

Filters are built from matchers and modifiers. Matchers are specific questions, like

  • is it made of wood?
  • is he/she on the Red Team?
  • is it inside region X?
  • has the match run past 5 minutes?

Modifiers can combine questions using logic, such as

  • A and B
  • A or B
  • not A
  • (A or B) and not (A and B)

Modifiers can also transform the meaning of questions, or answers, in various ways.

The documentation for other modules will explain where filters can be used, and how the filter affects the module’s behavior. Generally, other modules use filters in one of two ways:

  • Passively, which means whenever the module wants to do its thing, it will check the filter to decide if it should be done or not.
  • Dynamically, in which case the filter will notify the module when it's time to do something, and who or what it should be done to.

Only filters labeled Dynamic are capable of the latter. Modules that require dynamic filters will say so in their documentation.


Some filters don’t make sense in certain contexts. For example, you can’t ask if a block is on the Red Team, or if a player is made of wood, or if the match is inside a region.

Some modules will generate an error if you try to use the wrong type of filter, but other modules may allow it. When a filter doesn’t apply to a particular decision, it will abstain from that decision, and things will behave as they would if the filter didn’t exist. Generally, you should avoid using filters in such a way that they can abstain, since it tends to be confusing.

However, the event rules module uses filter abstention to make very complex conditions easier to express: It accepts a chain of filters, and uses the first filter in the chain that doesn’t abstain.

Filters can be forced to abstain using the <allow> and <deny> modifiers.

Defining Filters

Filters can be defined inside the top-level <filters> element, and assigned an id used to reference them elsewhere.

    <any id="filter-name">
        <!-- Filter elements -->

    <team id="viridescent-team-filter">viridescent-team</team>

    <!-- More filters-->

Matcher Elements

Filter matchers test for specific conditions or properties of things.

Element Description
Generic filters (apply to anything)
<filter id="filter1"/> Reference a filter by its ID. Dynamic
<always/> Matches/allows everything.
Can be referenced with the ID always
<never/> Matches nothing/denies everything.
Can be referenced with the ID never
<match-started/> Filter if the match has started. Dynamic
<match-running/> Filter if the match is running. Dynamic
<match-finished/> Filter if the match is over. Dynamic
<time>duration</time> Filter if the specified time period has elapsed since the match started. Dynamic
<completed>objective_id</completed> Match if the objective is completed. Dynamic
<captured>objective_id</captured> Match players or teams who currently control the objective. Dynamic
<flag-carried>flag_id</flag-carried> Match if the flag is being carried by anyone. Dynamic
<flag-dropped>flag_id</flag-dropped> Match if the flag is dropped on the ground. Dynamic
<flag-returned>flag_id</flag-returned> Match if the flag is at the return-point. Dynamic
<flag-captured>flag_id</flag-captured> Match if the flag has been captured. Dynamic
Spatial filters (apply to anything with a physical location)
<void/> Match if there is an air block at Y=0 in the vertical column of this location
Any region element
Block filters
<material>block</material> Matches blocks by their Material name.
Accepts a Single Material Pattern
<structural-load>2</structural-load> Test the number of other gravity blocks that the queried block is supporting.
Entity filters
<spawn>spawn reason</spawn> Matches spawn event reasons, see mob spawning
<mob>mob name</mob> Matches mobs by their name, see mob spawning
<entity>entity name</entity> Match entities, e.g. projectiles, boats, dropped items, etc.
Competitor filters (apply to teams, or FFA players)
<rank> </rank> Match if the player or team's rank is within the specified range. Dynamic
<score> </score> Match if the player or team's score is within the specified range. Dynamic
<carrying-flag>flag_id</carrying-flag> Match the team/player carrying the specified flag. Dynamic
Player filters
<participating/> Match if the player is participating in the match. Dynamic
<observing/> Match if the player is observing the match. Dynamic
<team>team</team> Matches a team by its ID. Dynamic
<class>class name</class> Match players with the specified class.
<kill-streak/> Match players with a certain range or amount of kills.
<crouching/> Match if the player is crouching. Dynamic
<walking/> Match if the player is walking. Dynamic
<sprinting/> Match if the player is sprinting. Dynamic
<flying/> Match if the player is flying. Dynamic
<can-fly/> Match if the player can fly.
<gliding/> Match if the player is gliding with an elytra. Dynamic
<grounded/> Match if the player is on the ground. Dynamic
<carrying><item material=""/></carrying> Match if the player is carrying an item.
<holding><item material=""/></holding> Match if the player is holding an item.
<wearing><item material=""/></wearing> Match if the player is wearing an item.
Event filters (apply to transient events)
<cause>cause</cause> Filter an event's cause.
<random>decimal or range</random> Random chance matcher.
Damage filters (apply to damage/combat events)
<relation>relation</relation> Filter an event's relation to the player.

Modifier Elements

Filter modifiers are used to alter the meaning of other filters, and combine them into more complex conditions. These elements must contain either a single filter, or a list of filters, as their child elements.

Name Description
Logic - combine other filters
<not> Invert the filters result; allow if the child filter denies, deny if it allows, abstain otherwise. Dynamic
<one> Allow if only one of the child filters allows, deny if one or more allow or none allow and at least one denies, otherwise abstain. Dynamic
<all> Allow if all of the child filters allow, deny if one or more deny, otherwise abstain. Dynamic
<any> Allow if one of the child filters allows, deny if none allow and at least one denies, otherwise abstain. Dynamic
Abstention - force filters to abstain
<allow> Allow if the child filter allows, otherwise abstain (transform deny to abstain).
<deny> Deny if the child filter allows, otherwise abstain.
Query modifiers - change the question
<same-team> Change a player question to a team question.
For example, "do they have the flag?" becomes "does their team have the flag?".
<victim> Make a damage question specifically about the victim.
For example, "do they have the flag?" becomes "does the victim have the flag?"
Commonly used with the damage module.
<attacker> Make a damage question specifically about the attacker.
For example, "do they have the flag?" becomes "does the attacker have the flag?"
Commonly used in the damage module.
Mechanisms - apply complex mechanics to other filters
<players> Count the number of players that match the inner filter. Dynamic
<countdown> Countdown from the moment that the inner filter matched. Dynamic


    <not id="deny-yellow-explosions">
    <deny id="no-tnt"><material>TNT</material></deny>

The player wants to place a TNT block, the filter gets asked; “Is this block place-able?”. The filter checks the <material> matcher, it matches and returns ALLOW. The material matcher is contained in a <deny> modifier so the ALLOW gets turned into a DENY.

Kill-Streak Filter

The kill-streak filter is a matcher that matches players who have a specified number of kills. The kill counter can be set to count from the start of the match or from the last time the player died. This filter is commonly used in kill rewards but can also be used to restrict access to certain locations, etc.

Kill-Streak Filter Attributes
Attribute Description Value Default
min Match players with at-least this many kills. Number
max Match players with a maximum of this many kills. Number
count Match players with exactly this many kills.
Can not be mixed with the min & max attributes.
repeat Repeat the filter range true/false false
persistent Do not reset a players kill count when they die. true/false false


<kill-streak min="3"/>      <!-- matches players with at least 3 kills -->
<kill-streak max="5"/>      <!-- matches players with at most 5 kills -->
<kill-streak count="4"/>    <!-- matches players with exactly 4 kills -->

<kill-streak id="10th-kill-filter" repeat="true" count="10"/>    <!-- match for every 10th kill -->

Random Filter

This filter will randomly ALLOW or DENY when evaluated in the context of an event. Its value is a decimal fraction between 0 and 1, representing the probability of ALLOW.

The value can also be an interval, in the form [0, 1). When the filter is evaluated, a random number is chosen, and the filter passes if the number falls within the filter’s interval. Multiple filters applied to the same object at the same instant will use the same random number. So, if their intervals do not overlap, the filters will never both pass at the same time. Using intervals in this way, any number of filters can be made mutually exclusive, or their relationships can be controlled in more complex ways.

A random filter can only be applied to instantaneous events, and not to conditions that persist over some span of time. Specifically, they can be used in the following contexts:

  • Regional block change rules
  • Block drop rules
  • Damage rules
  • Mob spawning rules

In other contexts, random filters will ABSTAIN.


<!-- 50% chance that it will return either ALLOW or DENY -->

<!-- Also a 50% chance -->
<!-- Any number from 0.25 to 0.75 including 0.25 but excluding 0.75 -->
<random>[0.25, 0.75)</random>

Rank & Score Filters

The rank and score filters match if the team’s or player’s rank or score is a equal to a single value or within a range of values.
The value can be an exact amount or a interval specifying a range. Only whole numbers are valid.


<!-- Match if the team (or player in ffa) rank is 3 -->

<!-- Match if team (or player in ffa) has a score from 5 to 10. -->

Player Count Filter

This filter counts the number of players matching a single child filter, and matches if that count is within a specified range.

The child filter can be omitted, in which case all players in the match will be counted.

Player Count Filter Attributes
Attribute Description Value Default
min Minimum player count Number 1
max Maximum player count Number oo (unlimited)
participants Include participants (players actually playing) in the count. true/false true
observers Include observers in the count. true/false false


<!-- Match if there are at least 4 players participating -->
<players min="4"/>

<!-- Match if there are 1 to 3 players sneaking in region X -->
<players min="1" max="3">
        <region id="X"/>

Countdown Filter

This filter matches for up to the specified amount of time after the child filter starts matching. It never matches when the child filter doesn’t match.

Countdown Filter Attributes
Attribute Description Value Default
duration Length of time to match for Time Period
message Optional timer message to display while counting down. Only players who match the filter can see the timer. If the message contains a placeholder, it will be replaced with the remaining time. Message Template


<!-- Countdown 30s from the moment any player picks up the flag -->
<!-- (you could then use the countdown filter to kill them, teleport them, etc) -->
<countdown duration="30s" message="You have {0} to capture the flag">

Objective Filters

There are two filter types that test the state of an objective: <completed> and <captured>. Both types require the ID of an objective as the content of the tag.

The <completed> filter matches when the specified objective is completed or captured by anybody e.g. when a destroyable is destroyed, a core is leaked, or a hill is captured by anyone. This filter is not affected by the context in which it is applied, and never abstains.

The <captured> filter matches players or teams who currently control the specified objective. This filter is useful for objectives that can change ownership, such as hills and flags. For other objective types, it will match players/teams who are allowed to complete the objective, if the objective is completed, which is generally not useful. This filter will abstain if used in a context that does not involve a specific player or team.

Alternately, <captured> can have a team specified with the team attribute. Then it will always test that team’s control of the objective, regardless of the filtering context, and will never abstain.

Capture Filter Attributes
Attribute Description Value
team Match only if the objective is captured/completed by this team. Team ID


<!-- Match if red-core has been leaked -->

<!-- Match if south-hill is owned by anyone -->

<!-- Match players/teams who own north-hill -->

<!-- Match if blue-team owns central-hill -->
<captured team="blue-team">central-hill</captured>

Flag Filters

The flag filters allow filtering of a specific flags current state or for the player that is carrying the flag. One important use of these filters is to implement the standard rule that a team can only capture an enemy flag when their own flag is returned. This can be implemented easily using a <flag-returned> as the capture-filter of a flag. This can also be done with the nets return attribute. However, using the return attribute will return dropped flags, while using a filter will not.

The flag carried, dropped, captured and returned filters have an optional post attribute to only match if the flag was last returned to that post.

<!-- The blue flag is currently being carried by a player -->

<!-- The blue flag has been carried away & dropped from the red-post -->
<flag-dropped post="red-post">blue-flag</flag-dropped>

<!-- The yellow flag is standing at one of its posts -->

<!-- The yellow flag is standing at the green-post -->
<flag-returned post="green-post">yellow-flag</flag-returned>

<!-- The cyan flag has been captured but not yet returned -->

<!-- The player currently carrying the purple flag -->

Item Filters

These filters can be used to filter for players with specific items in their inventory. They accept a single item element. Only the item’s type, durability/damage and meta data are compared. A item’s meta data includes the item’s name, enchantments, etc.

<!-- Player has a stick named 'Blue Door Key' in their inventory -->
<carrying><item name="Blue Door Key" material="stick"/></carrying>

<!-- Player is holding a clock -->
<holding><item material="clock"/></holding>

<!-- Player is wearing a chainmail chestplate -->
<wearing><item material="chainmail chestplate"/></wearing>

Event Cause Filters

Cause filters are used to filter an event or action according to its cause.

Element Description
<cause> </cause> Filter an event's cause.
Cause: Actor Type
WORLD World events such as ice melting, etc.
LIVING Events caused by a living entity.
MOB Events caused by a mob.
PLAYER Events caused by a player.
Cause: Block Action
PUNCH Events where a block is punched.
TRAMPLE Events where a block is trampled.
MINE Events where a block is mined.
Cause: Damage Type
GRAVITY Fall and void damage. VOID

Player Relation Filters

The relation filter is used when a player is damaged to check the relation between them and the damage cause. This filter is only used in damage related contexts i.e., damage filters, and kill rewards

Element Description
<relation> </relation> The relation between the player and their damage cause.
NEUTRAL Event has no attacker, e.g. world damage.
SELF Events caused by the player. (Same player same team)
ALLY Events caused by a player on the same team. (Different player same team)
ENEMY Events caused by an enemy player. (Different team)

Structural Load Filters

The structural load filter checks the number of gravity blocks that are attached to the queried block. It returns ALLOW as long as the structural load is greater than or equal to the specified value and DENY otherwise.

Warning This filter is very computationally expensive to apply, XML authors should ensure that it is only run when absolutely necessary, e.g. by placing other filters above it. They should also not apply it to events that modify large amounts of blocks, such as explosions.

This filter requires the falling blocks module to be loaded otherwise it will default to abstain.


<!--  Deny breaking structures longer than 3 blocks  -->
        <filter name="structure-blocks"/>

Void Filter

If your map is especially complex shaped you may have to use the <void/> tag to shape your filtered region. The <void/> tag checks the specified regions for blocks on the bottom layer of the world. It then creates an outline of those blocks and the specified filter is only active inside or outside that outline. Bridges are usually not detected because they are not at y=0. This can be fixed by creating a invisible silhouette of the bridge with block 36 at y=0.


    <not id="no-void">
    <apply block="no-void" message="You may not modify the void area!">
            <rectangle id="main-area" min="65,860" max="290,980"/>