All Conditions

Conditions and Filters Reference

This document serves as the primary manual for the Condition System, the decision-making engine behind every effect. Conditions act as "Gatekeepers"; they analyze the entity, the environment, and the beacon's status to determine if an effect should be applied.

This guide details every available condition type, its behavioral nuances, and configuration parameters.

---

Core Concepts

The Evaluation Cycle

Conditions are checked every single time the beacon "ticks" (updates). If a player meets the condition on Tick A but drops their required item before Tick B, the effect will immediately cease on the next update.

Negation

Every condition supports the Negate: true parameter. This inverts the result.

• Normal: "Does the player have Permission X?" -> Yes -> Allow.
• Negated: "Does the player have Permission X?" -> Yes -> Deny.

---

Player & Identity Conditions

HAS_PERMISSION

Evaluates the player's permissions list. This is the most efficient and common way to restrict effects to Ranks, VIPs, or Staff.

Dynamic Capabilities: This condition supports Placeholders within the permission node itself. This allows for advanced, dynamic permission checks based on other variables.

• Static Example: beaconplus.vip checks strictly for that node.
• Dynamic Example: beaconplus.level.{level} would verify if the player has beaconplus.level.5 if they are currently Level 5.

Parameters

Parameter	Type	Default	Function
Permission	Text	null	The permission node string to evaluate. Case-sensitive depending on your permission plugin.
Negate	True/False	false	If true, the condition passes only if the player lacks the permission.

Example: The Regulars Only

- Type: HAS_PERMISSION
  Permission: "group.default"
  Negate: true # Only allow people who are NOT in the default group

---

IS_HOLDING

Inspects the item held in the user's Main Hand. This is a strict "Identity Check" of the item. It matches not just the material, but the display name, lore, and custom model data. This enables "RPG Class" mechanics where holding a "Cleric's Wand" (Stick) grants regeneration.

Parameters

Parameter	Type	Default	Function
Item	Item Section	null	The template to match against.
Negate	True/False	false	If true, passes only if the player is holding anything else.

Behavioral Notes

• Amount Ignored: The evaluation ignores stack size. Holding 1 Diamond Sword is treated the same as holding 2.
• Strict Meta: If the configuration specifies a Name, an item of the same Material without the name will fail. Conversely, an item with the name but wrong Material will also fail.

Example: The King's Scepter

- Type: IS_HOLDING
  Item:
    type: GOLDEN_HOE
    meta:
      display-name: "&6King's Scepter"
      custom-model-data: 1234

---

IS_ITEM_IN_HAND_ENCHANTED

Scans the item in the Main Hand for a specific enchantment and level.

Parameters

Parameter	Type	Default	Function
Enchantment	Text	null	The official enchantment name (e.g., DAMAGE_ALL for Sharpness).
Level	Number	0	The minimum required level.
Negate	True/False	false	Inverts the check.

Example: Sharpness V Requirement

- Type: IS_ITEM_IN_HAND_ENCHANTED
  Enchantment: DAMAGE_ALL
  Level: 5

---

HAS_ITEM

Performs a deep scan of the player's Entire Inventory, including the Armor slots, Offhand, and Main Inventory.

Parameters

Parameter	Type	Default	Function
Item	Item Section	null	The template to search for.
Negate	True/False	false	If true, the user must not have the item anywhere.

Behavioral Notes

• Cumulative Counting: The system counts the total amount found. If you require 64 diamonds, having two stacks of 32 in different slots satisfies the condition.
• Performance Caution: Scanning 41 slots (Inventory + Armor + Offhand) for every player, every second, is a "heavy" operation. On servers with >100 players, purely permission-based checks are lighter.

Example: The Emerald Ticket

- Type: HAS_ITEM
  Item:
    type: PAPER
    meta:
      display-name: "&aEntry Ticket"

---

HAS_EFFECT

Checks if the player currently suffers from (or enjoys) a specific status effect.

Parameters

Parameter	Type	Default	Function
Effect	Text	null	The Potion Effect name (e.g., POISON).
Negate	True/False	false	If true, passes only if the player is free of the effect.

Example: The Cure Station Only applies checks to players who are actually poisoned.

- Type: HAS_EFFECT
  Effect: POISON

---

Entity & Type Filtering

TYPE_FILTER

This is the powerful engine used to target specific Mobs. It employs a String-Based Logic Parser, allowing you to write complex sentences to define your target group.

The Filter Syntax You can combine keywords using Boolean Operators:

• and / && : Both must be true.
• or / || : Either can be true.
• not / ! : Inverts the next term.
• xor : One must be true, but not both.
• () : Parentheses group logic.

Available Keywords (Case Insensitive)

• Categories:
  • MONSTER: Skeletons, Zombies, Creepers, etc.
  • ANIMALS: Cows, Pigs, Sheep, etc.
  • TAMED: Any animal that has an owner (Dogs, Cats).
  • ENEMY: Any entity currently targeting a player.
• Specific Types: ZOMBIE, SKELETON, VILLAGER, IRON_GOLEM, etc.

Parameters

Parameter	Type	Default	Function
Filter	Text	null	The logic string.

Examples

1. Target only Hostiles, but save the Creepers: Filter: "MONSTER and !CREEPER"
2. Target generic animals, but ignore Pets: Filter: "ANIMALS and !TAMED"
3. Target Undead only: Filter: "ZOMBIE or SKELETON or WITHER_SKELETON"

---

Environment & World

WORLD_WHITELIST

A valid-or-invalid check against the list of loaded world names.

Parameters

Parameter	Type	Default	Function
World List	List	[]	Exact names of allowed worlds.

Example: Nether Only

- Type: WORLD_WHITELIST
  World List:
    - "world_nether"

---

Beacon Status Conditions

POWER_REQUIREMENT

Inspects the total "Pyramid Power" generated by the physical blocks (Gold/Iron/Emerald) beneath the beacon.

Parameters

Parameter	Type	Default	Function
Minimum	Number	-1	The lowest allowed power level.
Maximum	Number	-1	The highest allowed power level.

Behavioral Notes

• This checks the Potential power, not the used power. It verifies the physical size and quality of the pyramid.

---

FREE_POWER_REQUIREMENT

Perform strict math: Available = TotalPower - UsedPower. This condition creates a "Budgeting" system where players cannot activate too many high-tier effects if their pyramid is too small.

Parameters

Parameter	Type	Default	Function
Minimum	Number	-1	The amount of "spare change" power required.

Example: Budget Check "You must have 50 spare power to activate Regeneration".

- Type: FREE_POWER_REQUIREMENT
  Minimum: 50

---

TOTAL_ACTIVE_BEACON_EFFECTS

Counts the number of distinct effects running on the beacon. It does not count Tiers; Speed 1 and Speed 2 are usually treated as the "Speed" effect family, but depending on configuration might be distinct.

Parameters

Parameter	Type	Default	Function
Maximum	Number	-1	The cap. If the beacon has more effects than this running, the condition fails.

---

Access Control Integration

These conditions interface directly with the Beacon's UI Whitelist.

• IS_WHITELISTED: Checks if the player's name appears on the whitelist page.
• IS_BLACKLISTED: Checks if the player's name appears on the blacklist page.
• HAS_WHITELIST: Checks if the specific beacon is currently set to "Whitelist Mode".
• HAS_BLACKLIST: Checks if the specific beacon is currently set to "Blacklist Mode".

Usage Tip: You usually want to combine these. For example, "Allow Access IF (Player is Whitelisted AND Mode is Whitelist) OR (Mode is Public)".

---

Logic Groups (AND/OR)

You can nest conditions infinitely to create complex decision trees.

AND_LOGIC

Requires every single condition in the list to pass. If even one fails, the entire group fails.

• Optimization Tip: Place the "Fastest" checks first. If the first check (e.g. Permission) fails, the system stops checking the others (e.g. Inventory Scan), saving performance.

Example

- Type: AND_LOGIC
  Conditions:
    - Type: HAS_PERMISSION
      Permission: "vip"
    - Type: IS_HOLDING
      Item:
        type: DIAMOND

OR_LOGIC

Requires only one condition to pass. If the first one passes, the system skips the rest and approves access.

Example

- Type: OR_LOGIC
  Conditions:
    - Type: HAS_PERMISSION
      Permission: "admin"
    - Type: HAS_PERMISSION
      Permission: "moderator"

---

Configuration Examples

Example A: Class Requirement Combines permission and item checks.

- Type: AND_LOGIC
  Conditions:
    - Type: HAS_PERMISSION
      Permission: "rpg.class.paladin"
    - Type: IS_HOLDING
      Item:
        type: GOLDEN_SWORD
        meta:
          display-name: "&6Holy Blade"

Example B: Entity Target Filter Restricts logic to specific entity groups.

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

Example C: Rank or Item Allows access via either permission or physical token.

- Type: OR_LOGIC
  Conditions:
    - Type: HAS_PERMISSION
      Permission: "rank.vip"
    - Type: HAS_ITEM
      Item:
        type: PAPER
        meta:
          display-name: "&bVIP Trial Token"