Events

This system allows you to automatically stop a player's flight when a specific event occurs on your server.

Welcome to the Universal Event Filter, a powerful yet highly optimized system that gives you unmatched flexibility over flight control. This feature allows you to seamlessly integrate CatzFly with your entire server by automatically stopping flight in response to specific events such as a player entering combat, taking damage, or interacting with another plugin's features. Best of all, this is achieved without needing any extra compatibility patches, ensuring clean and efficient performance.

Rule Structure

The entire system is based on a set of "rules" you define. Each rule listens for a specific server event and, if all conditions are met, performs an action.

unique_rule_id:
  # Set to true to activate this rule, false to disable it.
  enabled: true
  # REQUIRED: The event the rule will listen for.
  event-class: "EntityDamageEvent"
  # (Optional) Only listen for events from a specific plugin. Use '*' for any.
  plugin-name: "*"
  # The action to perform when the rule is triggered.
  action: "STOP_FLIGHT"
  # The message to send to the player. Supports color codes.
  message: "&cFlight has been disabled due to combat!"
  # (Optional) Cooldown in seconds before this rule can trigger again for the same player.
  cooldown: 3
  # (Optional) Players with this permission node will ignore this rule.
  permission: "catzfly.bypass.damage"
  # (Optional) A list of worlds where this rule applies. An empty list means all worlds.
  worlds: []
  # (Optional) A list of extra conditions that must ALL be true.
  conditions:
    - "event.cause=ENTITY_ATTACK"

Key Explanations

Key	Description
enabled	true / false. Determines if the rule is active.
event-class	Required. The server event to listen for. For Bukkit events, use the simple name (e.g., PlayerTeleportEvent). For custom events from other plugins, you must use the full class path (e.g., com.sk89q.worldguard.protection.events.DisallowedPVPEvent).
plugin-name	(Optional) Makes the rule only react to events from a specific plugin (e.g., CombatLogX). Use "*" to listen regardless of the source. This is highly recommended for accuracy.
action	The action to take. Options are: STOP_FLIGHT, CANCEL_EVENT (if the event is cancellable), STOP_AND_CANCEL, or WARN (only sends the message).
message	The message sent to the player when the rule is triggered.
cooldown	(Optional) The time in seconds before this rule can affect the same player again. Useful for preventing spam from rapid events like poison damage.
permission	(Optional) Players with this permission will be immune to this rule.
worlds	(Optional) A list of world names where this rule is active. An empty list [] means it's active in all worlds.
conditions	(Optional) A list of extra checks that must all pass for the rule to trigger. See the reference below for available conditions.

Conditions Reference

Conditions allow you to make your rules extremely specific.

Player Conditions

• "player.health<20": Player's health is less than 20.

• "player.health>10": Player's health is greater than 10.

• "player.sneaking": The player is sneaking.

• "player.sprinting": The player is sprinting.

• "player.gamemode=SURVIVAL": The player is in a specific gamemode (CREATIVE, ADVENTURE, SPECTATOR).

Event Conditions (Mainly for EntityDamageEvent)

• "event.damage>5": The damage amount is greater than 5.

• "event.cancelled": The event has already been cancelled by another process.

• "event.cause=CAUSE_NAME": The cause of the damage matches a specific type. Common causes include:

  • FALL, ENTITY_ATTACK, PROJECTILE, LAVA, FIRE_TICK, DROWNING, VOID, MAGIC.

How to Find Custom Event Information

To integrate with other plugins, you often need two key pieces of information:

• plugin-name: You can usually find the plugin's exact name from its plugin.yml file or as it loads in the server console.

• event-class: This part may be confusing for beginners. You typically need to consult the other plugin's documentation, developer API (Javadocs), or source code to find the full path of the event you want to use.

Practical Examples

Here are some ready-to-use examples for popular plugins to guide you.

Example 1: CombatLogX This rule listens for a player being tagged by CombatLogX and immediately disables their flight. This is a perfect way to prevent players from flying away during PvP.

combat_tag_on:
  enabled: true
  event-class: "PlayerTagEvent"
  plugin-name: "CombatLogX"
  action: "STOP_FLIGHT"
  message: "&cYou cannot fly while in combat!"

Example 2: MythicMobs This rule triggers when a MythicMob is killed. You could use this to pause flight at the end of a boss fight for cinematic effect or safety. Note that for modern MythicMobs versions, you often need the full event path.

mythic_boss_killed:
  enabled: true
  event-class: "io.lumine.mythic.bukkit.events.MythicMobDeathEvent"
  plugin-name: "MythicMobs"
  action: "WARN"
  message: "&aThe great beast has been defeated! Your flight is paused."