Filters

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.

ElementDescription
Generic filters (apply to anything)
Reference a filter by its ID.Dynamic
Matches/allows everything.
Can be referenced with the ID
Dynamic
Matches nothing/denies everything.
Can be referenced with the ID
Dynamic
Filter if the specified time period has elapsed since the match started.Dynamic
Match if the objective is completed.Dynamic
Match if the flag is being carried by anyone.Dynamic
Match if the flag is dropped on the ground.Dynamic
Match if the flag is at the return-point.Dynamic
Match if the flag has been captured.Dynamic
Spatial filters (apply to anything with a physical location)
Match if there is an air block at Y=0 in the vertical column of this location
Any region element
Block filters
Matches blocks by their Material name.
Accepts a Single Material Pattern
Test the number of other gravity blocks that the queried block is supporting.
Entity filters
Matches spawn event reasons, see mob spawning
Matches mobs by their name, see mob spawning
Match entities, e.g. projectiles, boats, dropped items, etc.
Competitor filters (apply to teams, or FFA players)
Match the team/player carrying the specified flag.Dynamic
Player filters
Match if the player is participating in the match.Dynamic
Matches a team by its ID.Dynamic
Match players with the specified class.
Match players with a certain range or amount of kills.
Match if the player is crouching.Dynamic
Match if the player is walking.Dynamic
Match if the player is sprinting.Dynamic
Match if the player is flying.Dynamic
Match if the player can fly.
Match if the player is carrying an item.
Match if the player is holding an item.
Match if the player is wearing an item.
Event filters (apply to transient events)
Filter an event's cause.
Random chance matcher.
Damage filters (apply to damage/combat events)
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.

NameDescription
Logic - combine other filters
Invert the filters result; allow if the child filter denies, deny if it allows, abstain otherwise.Dynamic
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
Allow if all of the child filters allow, deny if one or more deny, otherwise abstain.Dynamic
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 if the child filter allows, otherwise abstain (transform deny to abstain).
Deny if the child filter allows, otherwise abstain.
Query modifiers - change the question
Change a player question to a team question.
For example, "do they have the flag?" becomes "does their team have the flag?".
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.
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

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>

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
AttributeDescriptionValueDefault
Match players with at-least this many kills.Number
Match players with a maximum of this many kills.Number
Match players with exactly this many kills.
Can not be mixed with the & attributes.
Number
Repeat the filter rangetrue/falsefalse
Do not reset a players kill count when they die.true/falsefalse

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>

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
AttributeDescriptionValueDefault
Minimum player countNumber1
Maximum player countNumberoo (unlimited)
Include participants (players actually playing) in the count.true/falsetrue
Include observers in the count.true/falsefalse

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.

ElementDescription
Filter an event's cause.
Cause: Actor Type
World events such as ice melting, etc.
Events caused by a living entity.
Events caused by a mob.
Events caused by a player.
Cause: Block Action
Events where a block is punched.
Events where a block is trampled.
Events where a block is mined.
Cause: Damage Type
Fall and void damage.

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

ElementDescription
The relation between the player and their damage cause.
Values
Event has no attacker, e.g. world damage.
Events caused by the player. (Same player same team)
Events caused by a player on the same team. (Different player same team)
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.

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>