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
Filters can be defined inside the top-level
and assigned an
id used to reference them elsewhere.
Filter matchers test for specific conditions or properties of things.
|Generic filters (apply to anything)|
|Reference a filter by its ID.||Dynamic|
Can be referenced with the ID
|Matches nothing/denies everything.|
Can be referenced with the ID
|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|
|Matches blocks by their Material name.|
Accepts a Single Material Pattern
|Test the number of other gravity blocks that the queried block is supporting.|
|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|
|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.|
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.
|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|
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
|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.
|Repeat the filter range||true/false||false|
|Do not reset a players kill count when they die.||true/false||false|
This filter will randomly
DENY when evaluated in the context of an event.
Its value is a decimal fraction between 0 and 1, representing the probability of
The value can also be an interval, in the form
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
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
|Minimum player count||Number||1|
|Maximum player count||Number||oo (unlimited)|
|Include participants (players actually playing) in the count.||true/false||true|
|Include observers in the count.||true/false||false|
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.
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.
Event Cause Filters
Cause filters are used to filter an event or action according to its cause.
|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
|The relation between the player and their damage cause.|
|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.
ALLOW as long as the structural load is greater than or equal to the specified value and
If your map is especially complex shaped you may have to use the
<void/> tag to shape your filtered region.
<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