All Conditions

All Conditions & Filters Reference

Conditions are the "brains" of BeaconPlus. They determine who receives an effect, when an upgrade is possible, and which entities are ignored. This document provides a deep dive into the condition system, logic gates, and filtering syntax.

---

1. Condition Fundamentals

Every condition in BeaconPlus is a map containing a Type and optional logic flags.

• Type: The ID of the condition logic.
• Negate: (Boolean) If set to true, the condition's result is flipped. A "Success" becomes a "Failure", and vice versa.
• Performance Note: Simple conditions (like HAS_PERMISSION) are processed instantly. Complex filters (like TYPE_FILTER) or those scanning inventories (HAS_ITEM) have a higher processing cost. In a server with hundreds of beacons, avoid unnecessary inventory scans.

---

2. Player & Item Conditions

HAS_PERMISSION

Checks if the target player possesses a specific permission node.

• Mechanics: Uses the standard Vault/Permissions API.
• YAML Example:

  - Type: HAS_PERMISSION
    Permission: "beaconplus.vip.perks"
    Negate: false

IS_HOLDING

Checks what item the player is currently holding in their main hand.

• Mechanics: Compares the held item against a template. Supports NBT, display names, and materials.
• YAML Example:

  - Type: IS_HOLDING
    Item:
      type: NETHERITE_SWORD
      meta:
        display-name: "&6Excalibur"

HAS_ITEM

Scans the player's entire inventory for a specific item.

• Precautions: This is more performance-intensive than IS_HOLDING. Use it sparingly if the beacon range is very large or if there are many entities.
• YAML Example:

  - Type: HAS_ITEM
    Item:
      type: EMERALD
      amount: 64

IS_ITEM_IN_HAND_ENCHANTED

Specifically checks for enchantments on the held item.

• Parameters:
  • Enchantment: The name of the enchantment (e.g., SHARPNESS, DIG_SPEED).
  • Level: The minimum level required.
• YAML Example:

  - Type: IS_ITEM_IN_HAND_ENCHANTED
    Enchantment: "SHARPNESS"
    Level: 5

---

3. Entity & World Conditions

TYPE_FILTER

The most powerful tool for targeting specific mobs or groups.

• Mechanics: Uses a custom-built logical string parser.

• Filter Syntax Mastery:

  • Keywords: ANIMALS, MONSTER, CREATURE, TAMED, ENEMY, and any EntityType (e.g., ZOMBIE, CREEPER).
  • Operators: and (&&), or (||), xor (^), not (!).
  • Grouping: Use parentheses ( ) for complex priority.

• Examples:

  • MONSTER and not CREEPER: Affects all monsters except creepers.
  • ZOMBIE or SKELETON: Affects only those two types.
  • (ANIMALS or VILLAGER) and !TAMED: Affects wild animals and villagers, but ignores pets.

• YAML Example:

  - Type: TYPE_FILTER
    Filter: "MONSTER and !CREEPER"

WORLD_WHITELIST

Restricts the effect/condition to specific worlds.

• YAML Example:

  - Type: WORLD_WHITELIST
    World List:
      - world
      - world_nether

---

4. Beacon Logic & Power

POWER_REQUIREMENT

Checks the raw "Potential Power" of the beacon (based on its pyramid).

• YAML Example:

  - Type: POWER_REQUIREMENT
    Minimum: 100
    Maximum: 500

FREE_POWER_REQUIREMENT

Checks if the beacon has enough unused power. This is crucial for effects that should "shut down" if too many other things are running.

• YAML Example:

  - Type: FREE_POWER_REQUIREMENT
    Minimum: 10

TOTAL_ACTIVE_BEACON_EFFECTS

Checks how many different effects are currently toggled on at this beacon. Useful for "balancing" high-tier rewards.

---

5. Logic Gates (Nesting)

You can combine any number of conditions using logic gates. These gates can be nested indefinitely.

AND_LOGIC

Succeeds only if ALL nested conditions are met.

YAML Example:

- Type: AND_LOGIC
  Conditions:
    - Type: HAS_PERMISSION
      Permission: "beaconplus.vip"
    - Type: POWER_REQUIREMENT
      Minimum: 200

OR_LOGIC

Succeeds if AT LEAST ONE nested condition is met.

YAML Example:

- Type: OR_LOGIC
  Conditions:
    - Type: HAS_PERMISSION
      Permission: "beaconplus.admin"
    - Type: HAS_ITEM
      Item:
        type: NETHER_STAR

---

6. Access List Integration

Conditions can also target the beacon's unique Whitelist/Blacklist.

• IS_WHITELISTED: Success if the player is on the beacon's whitelist.
• IS_BLACKLISTED: Success if the player is on the beacon's blacklist.
• HAS_WHITELIST: Success if the beacon owner has actually enabled a whitelist.

---

Proactive Precautions for Server Owners

1. Logic Depth: While you can nest AND_LOGIC inside OR_LOGIC inside another AND_LOGIC, each layer adds a tiny amount of overhead. Try to flatten your logic where possible.
2. Filter Strings: Be precise in your TYPE_FILTER. Using (ZOMBIE or CREEPER or SKELETON or SPIDER) is slightly faster than MONSTER.
3. Permissions: Permissions are the most efficient way to handle player tiers. If you have "VIP Effects", use HAS_PERMISSION as the very first condition in an AND_LOGIC block to "short-circuit" the check for regular players.
4. Inventory Scans: Avoid using HAS_ITEM for effects that tick every second (like standard Potion effects) if you have many players. It forces the server to iterate through 36+ inventory slots every tick.