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.

Abstaining

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.

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

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

    <!-- More filters-->
</filters>

Matcher Elements

Filter matchers test for specific conditions or properties of things.

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.

Examples

<filters>
    <not id="deny-yellow-explosions">
        <all>
            <team>yellow</team>
            <cause>explosion</cause>
        </all>
    </not>
</filters>

<filters>
    <deny id="no-tnt"><material>TNT</material></deny>
</filters>

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

Examples

<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.

Examples

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

<!-- 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.

Examples

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

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

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

Examples

<!-- 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">
    <all>
        <sneaking/>
        <region id="X"/>
    </all>
</players>

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

Examples

<!-- 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">
    <carrying-flag>blue-flag</carrying-flag>
</countdown>

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

Examples

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

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

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

<!-- 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 -->
<flag-carried>blue-flag</flag-carried>

<!-- 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 -->
<flag-returned>yellow-flag</flag-returned>

<!-- 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 -->
<flag-captured>cyan-flag</flag-captured>

<!-- The player currently carrying the purple flag -->
<carrying-flag>purple-flag</carrying-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.

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

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.

Example

<!--  Deny breaking structures longer than 3 blocks  -->
<not>
    <all>
        <cause>player</cause>
        <filter name="structure-blocks"/>
        <structural-load>3</structural-load>
    </all>
</not>

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.

Example

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