### Example PlaceholderAPI Usage in Conditions

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Demonstrates how to use ConditionalEvents PlaceholderAPI expansions within a condition, such as checking if a cooldown is ready.

```yaml
conditions:
  - "%conditionalevents_cooldown_paid_announce% == Ready!"
```

--------------------------------

### PlaceholderAPI Expansions for ConditionalEvents

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Utilize PlaceholderAPI placeholders to display cooldowns, one-time event status, or general event enablement. Requires PlaceholderAPI to be installed.

```plaintext
# Returns remaining cooldown time or "Ready!"
%conditionalevents_cooldown_<event_name>%

# Returns "yes" if the one_time event has already fired for the player, "no" otherwise
%conditionalevents_onetime_ready_<event_name>%

# Returns "true" or "false"
%conditionalevents_is_enabled_<event_name>%
```

--------------------------------

### Basic Event Configuration Structure

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Defines a 'welcome_vip' event triggered by player join. It includes conditions based on PlaceholderAPI variables and specifies actions for default, cooldown, and one-time scenarios.

```yaml
# plugins/ConditionalEvents/events/my_events.yml
Events:
  welcome_vip:
    type: player_join               # trigger type (EventType enum, lowercase)
    enabled: true                   # default true; can be toggled with /ce enable|disable
    cooldown: 0                     # seconds; 0 = no cooldown
    one_time: false                 # if true, fires once per player lifetime
    ignore_with_permission: "conditionalevents.ignore.welcome_vip"
    ignore_if_cancelled: false      # skip if the underlying Bukkit event is already cancelled
    allow_math_formulas_in_conditions: false
    conditions:
      - "%player_has_permission_vip% == yes"   # PlaceholderAPI variable comparison
    actions:
      default:
        - "message: &6Welcome back, VIP player &e%player%&6!"
        - "title: 10;60;10;Welcome!;Have fun on the server"
        - "playsound: ENTITY_PLAYER_LEVELUP;1;1"
      cooldown:
        - "message: &cPlease wait &7%time% &cbefore triggering this again."
      one_time:
        - "message: &7You've already claimed your one-time reward."
```

--------------------------------

### Calling Call Events via Command and Action

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Demonstrates how to trigger a CALL event using the '/ce call' command with variables and targets, or programmatically from another event's actions.

```bash
# Trigger via command (with optional variables and target player)
/ce call give_reward %amount%=500 player:Steve

# Trigger silently from another action
# In another event's actions:
- "call_event: give_reward;%amount%=100;already_stored"

```

--------------------------------

### Basic Equality and String Operators

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Use basic equality operators (==, !=) and string matching operators (startsWith, contains, etc.) to define conditions based on player or event properties.

```yaml
conditions:
  # Basic equality operators: ==, !=, equals, !equals, equalsIgnoreCase, !equalsIgnoreCase
  - "%player_world% == spawn"
  - "%player_gamemode% != CREATIVE"

  # String matching: startsWith, !startsWith, contains, !contains, endsWith, !endsWith
  - "%main_command% startsWith /kit"
```

--------------------------------

### Sound and Title Actions

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Play custom sounds, resource pack sounds, or stop existing sounds. Display titles and subtitles with customizable fade-in, stay, and fade-out durations.

```yaml
- "playsound: ENTITY_PLAYER_LEVELUP;10;1"

```

```yaml
- "playsound_resource_pack: my.custom.sound;1;1"

```

```yaml
- "stopsound: ENTITY_PLAYER_LEVELUP"

```

```yaml
- "actionbar: &6You have &e%vault_eco_balance%&6 coins.;100"

```

```yaml
- "title: 10;70;10;Welcome!;Enjoy the server"

```

--------------------------------

### PlaceholderAPI Expansion

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Utilize PlaceholderAPI to access ConditionalEvents data. This allows displaying information like cooldowns, one-time event status, and event enablement within game interfaces.

```APIDOC
## PlaceholderAPI Expansion

### Description
When PlaceholderAPI is installed, the plugin registers a `%conditionalevents_...%` expansion to provide dynamic information about events.

### Placeholders
- `%conditionalevents_cooldown_<event_name>%`: Returns the remaining cooldown time for the specified event, or "Ready!" if the cooldown has expired.
- `%conditionalevents_onetime_ready_<event_name>%`: Returns "yes" if the one-time event has already fired for the player, and "no" otherwise.
- `%conditionalevents_is_enabled_<event_name>%`: Returns "true" if the specified event is currently enabled, and "false" otherwise.

### Example Usage
```yaml
conditions:
  - "%conditionalevents_cooldown_paid_announce% == Ready!"
```
```

--------------------------------

### Command Execution Actions

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Execute console commands, player commands, or player commands with OP privileges. This allows for integration with other server functionalities.

```yaml
- "console_command: give %player% diamond 1"

```

```yaml
- "player_command: spawn"

```

```yaml
- "player_command_as_op: some_admin_command"

```

--------------------------------

### Timing and Persistence Actions

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Control the flow of actions using 'wait' or 'wait_ticks'. Ensure items or experience are kept on death, or prevent item drops.

```yaml
- "wait: 3"

```

```yaml
- "wait_ticks: 60"

```

```yaml
- "keep_items: all"

```

```yaml
- "cancel_drop: true"

```

--------------------------------

### Entity and Server Event Types

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Covers trigger types for entity and server-wide events, including spawning, interaction, and server start/stop.

```yaml
# Entity / server events
type: entity_spawn
type: entity_interact      # player right-clicks an entity
type: console_command
type: server_start
type: server_stop
type: repetitive           # fires for each online player on a timer
type: repetitive_server    # fires once on a timer (no player context)
```

--------------------------------

### Basic Message Actions

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Send plain, centered, or broadcast messages to players. Use 'to_all' for all online players and 'to_range' for players within a specified radius.

```yaml
- "message: &aHello, %player%!"

```

```yaml
- "centered_message: &6Server Announcement"

```

```yaml
- "to_all: message: &e%player% &7joined the server."

```

```yaml
- "to_range: 20;true: message: &7Someone nearby picked up an item!"

```

```yaml
- "to_target: message: &cYou were attacked by &e%player%!

```

--------------------------------

### Server and Event Manipulation Actions

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Transfer players to different servers, cancel events, kick players, or modify player attributes like gamemode or fire status.

```yaml
- "send_to_server: lobby"

```

```yaml
- "cancel_event: true"

```

```yaml
- "kick: &cYou are not allowed here."

```

```yaml
- "gamemode: CREATIVE"

```

```yaml
- "set_on_fire: 100"

```

--------------------------------

### ConditionalEvents Global Configuration (`config.yml`)

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Configuration options for ConditionalEvents, including update notifications, data saving intervals, debug settings, message formatting, and command registration.

```yaml
Config:
  update_notification: true
  data_save_time: 5                  # minutes between auto-saves of player data
  retain_player_data_until_restart: true
  debug_actions: true                # enables /ce debug feature
  use_minimessage: false             # use MiniMessage formatting instead of legacy &-codes (Paper 1.19.3+)
  item_meta_variable_enabled: false  # enable %item_meta_...% variables (performance impact)
  experimental:
    variable_replacement: false      # experimental nested variable resolution
  register_commands:                 # register these as real server commands (for tab-complete, etc.)
    - "hello"
  to_condition_groups:               # reusable condition lists referenced with %to_condition_group_<name>%
    vip_check:
      - "%player_has_permission_vip% == yes"

Messages:
  prefix: '&4[&bConditionalEvents&4] '
  seconds: s
  minutes: m
  hours: h
  days: d
  placeholderAPICooldownReady: "Ready!"
  placeholderAPICooldownNameError: "No event with that name!"
  # ... (all command feedback messages are customizable here)
```

--------------------------------

### Admin Commands

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Manage ConditionalEvents functionality using a set of administrative commands. These commands allow reloading configurations, verifying events, debugging, managing event states, and more.

```APIDOC
## Admin Commands (`/ce` or `/conditionalevents`)

Requires `conditionalevents.admin` permission or OP.

### Command List
- `/ce reload`: Reload all event configuration files.
- `/ce verify`: Validate all events for syntax errors.
- `/ce debug <event_name> [player_name]`: Enable or disable debug output for a specific event, optionally scoped to a single player.
- `/ce enable <event_name>`: Toggle an event on, persisting the change to its configuration file.
- `/ce disable <event_name> [silent:true]`: Toggle an event off, persisting the change to its configuration file. The `silent:true` argument prevents feedback messages.
- `/ce reset <player_name|*> <event_name|all> [silent:true]`: Reset per-player data for cooldowns or one-time events. `*` can be used for all players, and `all` for all event types. `silent:true` prevents feedback.
- `/ce call <event_name> [variables...] [silent:true]`: Manually fire a CALL event with specified variables. Variables should be in the format `%name%=value`. `silent:true` prevents feedback.
- `/ce item save <item_name>`: Save the item currently held in hand under the specified name for use in `give_item:` actions.
- `/ce item remove <item_name>`: Remove a previously saved item.
- `/ce interrupt <event_name> [player_name] [silent:true]`: Interrupt currently running wait chains for a specified event and player. `silent:true` prevents feedback.
```

--------------------------------

### Repetitive and Repetitive Server Events

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Use 'repetitive' for player-specific interval events and 'repetitive_server' for server-wide interval events. Set 'repetitive_time' for the interval in seconds.

```yaml
Events:
  auto_gamemode_plotworld:
    type: repetitive
    repetitive_time: 10         # interval in seconds
    conditions:
      - "%player_world% == plotworld"
      - "%player_gamemode% != CREATIVE"
    actions:
      default:
        - "gamemode: CREATIVE"
        - "actionbar: &6Gamemode set to Creative.;100"

  hourly_broadcast:
    type: repetitive_server
    repetitive_time: 3600
    conditions: []
    actions:
      default:
        - "to_all: centered_message: &e&lHourly Reminder: Vote at vote.server.com!"

```

--------------------------------

### Using Registered API Actions in YAML

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Shows how to invoke custom Java API actions within your Conditional Events YAML configuration. The 'actionLine' passed to the Java code is the text following the action identifier.

```yaml
- "api: MY_REWARD 250"
- "api: SEND_DISCORD #general %player% just logged in"

```

--------------------------------

### Regex and Numeric Comparison Operators

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Utilize regular expressions for pattern matching and numeric comparison operators (>, >=, <, <=) for numerical evaluations in conditions.

```yaml
  # Regex: matches, !matches
  - "%player_name% matches [A-Za-z0-9_]+"

  # Numeric comparison: >, >=, <, <=
  - "%vault_eco_balance% >= 1000"
  - "%player_health% < 10"
```

--------------------------------

### Item Manipulation Actions

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Give items with specific properties (name, enchantments, slot), use saved items, drop items at coordinates, or remove items from inventory by ID or slot.

```yaml
- "give_item: id:DIAMOND_SWORD;amount:1;name:&bMy Sword;enchants:DAMAGE_ALL-5|DURABILITY-3;slot:HAND"

```

```yaml
- "give_item: saved_item:my_saved_sword"

```

```yaml
- "drop_item: location:100,64,200,world;id:DIAMOND;amount:3"

```

```yaml
- "remove_item: DIAMOND;5"

```

```yaml
- "remove_item_slot: HAND;1"

```

--------------------------------

### ConditionalEvents Admin Commands

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

A list of available admin commands for managing ConditionalEvents, including reloading, verification, debugging, enabling/disabling events, and resetting data.

```bash
# Reload all event config files
/ce reload

# Validate all events for syntax errors
/ce verify

# Enable/disable debug output for an event (optionally scoped to one player)
/ce debug paid_announce
/ce debug paid_announce Steve

# Toggle event on/off (persisted to file)
/ce enable  paid_announce
/ce disable paid_announce [silent:true]

# Reset per-player cooldown / one_time data
/ce reset Steve   paid_announce
/ce reset *       all           # reset everything for all players
/ce reset Steve   all [silent:true]

# Manually fire a CALL event
/ce call give_reward %amount%=500 player:Steve [silent:true]

# Save the item currently held in hand under a name (for give_item: saved_item:...)
/ce item save  my_sword
/ce item remove my_sword

# Interrupt currently-running wait chains for an event
/ce interrupt paid_announce
/ce interrupt paid_announce Steve [silent:true]
```

--------------------------------

### Math Formulas in Conditions

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Enable and use mathematical formulas within conditions by setting 'allow_math_formulas_in_conditions: true' in the configuration.

```yaml
  # Math formulas (requires allow_math_formulas_in_conditions: true)
  - "%player_health% + %player_food_level% > 30"
```

--------------------------------

### Player Command Event with Cooldowns and One-Time Logic

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Configures a player command event with a per-player cooldown, specific conditions to prevent cooldown activation, and actions for success, errors, and cooldown.

```yaml
Events:
  paid_announce:
    type: player_command
    cooldown: 30                         # 30-second per-player cooldown
    prevent_cooldown_activation:         # these groups do NOT start the cooldown
      - error_no_args
      - error_no_money
    one_time: false
    conditions:
      - "%main_command% == /announce"
      - "%args_length% == 0 execute error_no_args"
      - "%vault_eco_balance% < 500 execute error_no_money"
    actions:
      default:
        - "cancel_event: true"
        - "to_all: centered_message: &7%args_substring_1-100%"
        - "console_command: eco take %player% 500"
      error_no_args:
        - "cancel_event: true"
        - "message: &cUsage: /announce <message>"
      error_no_money:
        - "cancel_event: true"
        - "message: &cYou need $500 to announce."
      cooldown:
        - "cancel_event: true"
        - "message: &cWait &7%time% &cbefore announcing again."

```

--------------------------------

### World and Entity Manipulation Actions

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Modify blocks in the world, summon entities with custom properties, or create lightning strikes. These actions allow for dynamic world changes.

```yaml
- "set_block: location:100,64,200,world;id:STONE;block_data:facing=north"

```

```yaml
- "summon: location:100,64,200,world;entity:ZOMBIE;custom_name:&cGuard;health:40;amount:3"

```

```yaml
- "lightning_strike: world;100;64;200"

```

--------------------------------

### Player Command Events with Cooldowns and One-Time Options

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Events triggered by player commands, featuring configurable cooldowns and one-time execution settings.

```APIDOC
## Cooldowns and One-Time Events

```yaml
Events:
  paid_announce:
    type: player_command
    cooldown: 30                         # 30-second per-player cooldown
    prevent_cooldown_activation:         # these groups do NOT start the cooldown
      - error_no_args
      - error_no_money
    one_time: false
    conditions:
      - "%main_command% == /announce"
      - "%args_length% == 0 execute error_no_args"
      - "%vault_eco_balance% < 500 execute error_no_money"
    actions:
      default:
        - "cancel_event: true"
        - "to_all: centered_message: &7%args_substring_1-100%"
        - "console_command: eco take %player% 500"
      error_no_args:
        - "cancel_event: true"
        - "message: &cUsage: /announce <message>"
      error_no_money:
        - "cancel_event: true"
        - "message: &cYou need $500 to announce."
      cooldown:
        - "cancel_event: true"
        - "message: &cWait &7%time% &cbefore announcing again."
```
```

--------------------------------

### Redirecting on Condition Failure

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Specify an action group to execute if a condition fails by appending 'execute <group_name>' to the condition line.

```yaml
  # Redirect to named action group if condition FAILS
  - "%player_has_permission_vip% == yes execute no_permission_group"
```

--------------------------------

### Player Event Types

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Lists various trigger types for player-related events, such as joining, leaving, dying, and interacting with game elements.

```yaml
# Player events
type: player_join          # player connects
type: player_leave         # player disconnects
type: player_pre_join      # AsyncPlayerPreLoginEvent (before join)
type: player_death         # player dies
type: player_respawn       # player respawns
type: player_kill          # player kills another entity
type: player_attack        # player hits an entity
type: player_damage        # player receives damage
type: player_command       # player types a command
type: player_chat          # player sends chat message
type: player_levelup       # player gains XP level
type: player_world_change  # player changes world
type: player_teleport      # player teleports
type: player_sneak         # player toggles sneak
type: player_run           # player sprints
type: player_fish          # player fishes
type: player_bed_enter     # player enters bed
type: player_armor         # player equips/unequips armor
type: player_offhand       # player swaps offhand item
type: player_statistic     # player statistic changes
type: player_open_inventory
type: player_close_inventory
type: player_click_inventory
type: player_regain_health
type: player_change_air    # 1.10+
type: player_change_food   # 1.16+
type: player_tab_complete  # player presses TAB
```

--------------------------------

### Listen to ConditionalEventsEvent in Java

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Implement a Bukkit Listener to react when an event's conditions are met and an action group is about to run. Useful for auditing or custom logic.

```java
import ce.ajneb97.api.ConditionalEventsEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class CEListener implements Listener {

    @EventHandler
    public void onCEEvent(ConditionalEventsEvent event) {
        String eventName   = event.getEvent();       // ConditionalEvents event name
        String actionGroup = event.getActionGroup(); // "default", "cooldown", custom name, etc.
        // event.getPlayer() may be null for server-scope events
        if (event.getPlayer() != null) {
            event.getPlayer().sendMessage("[Audit] " + eventName + " → " + actionGroup);
        }
    }
}
```

--------------------------------

### Java API - `ConditionalEventsAPI`

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Provides programmatic access to Conditional Events functionality from other Bukkit plugins, including registering custom actions and querying event states.

```APIDOC
## Java API — `ConditionalEventsAPI`

The static API class exposes methods for querying event state and registering custom action types from other Bukkit plugins.

```java
import ce.ajneb97.api.ConditionalEventsAPI;
import ce.ajneb97.api.ConditionalEventsAction;
import org.bukkit.entity.Player;
import org.bukkit.event.Event;
import org.bukkit.plugin.java.JavaPlugin;

public class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        // Register one or more custom action types
        ConditionalEventsAPI.registerApiActions(this,
            new ConditionalEventsAction("MY_REWARD") {
                @Override
                public void execute(Player player, String actionLine, Event minecraftEvent) {
                    // actionLine is whatever comes after "api: MY_REWARD " in the YAML
                    int amount = Integer.parseInt(actionLine.trim());
                    player.sendMessage("You received " + amount + " points!");
                    // ... award points logic ...
                }
            },
            new ConditionalEventsAction("SEND_DISCORD") {
                @Override
                public void execute(Player player, String actionLine, Event minecraftEvent) {
                    // e.g., actionLine = "#general Hello from %player%"
                    getLogger().info("Discord: " + actionLine);
                }
            }
        );
    }

    @Override
    public void onDisable() {
        ConditionalEventsAPI.unregisterApiActions(this);
    }

    // Query event state at runtime
    public void exampleQueries(Player player) {
        // Get remaining cooldown time string (e.g., "14s") or "Ready!"
        String cooldown = ConditionalEventsAPI.getEventCooldown(player, "paid_announce");

        // Check whether a one_time event has already been triggered for the player
        String ready = ConditionalEventsAPI.getOneTimeReady(player, "daily_reward"); // "yes" or "no"

        // Check if an event is currently enabled
        boolean enabled = ConditionalEventsAPI.isEventEnabled("paid_announce");
    }
}
```

In YAML, the registered action is called with:
```yaml
- "api: MY_REWARD 250"
- "api: SEND_DISCORD #general %player% just logged in"
```
```

--------------------------------

### Registering Custom API Actions in Java

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Extends ConditionalEventsAction to create custom actions like 'MY_REWARD' or 'SEND_DISCORD' that can be used in YAML event definitions. Requires implementing the execute method.

```java
import ce.ajneb97.api.ConditionalEventsAPI;
import ce.ajneb97.api.ConditionalEventsAction;
import org.bukkit.entity.Player;
import org.bukkit.event.Event;
import org.bukkit.plugin.java.JavaPlugin;

public class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        // Register one or more custom action types
        ConditionalEventsAPI.registerApiActions(this,
            new ConditionalEventsAction("MY_REWARD") {
                @Override
                public void execute(Player player, String actionLine, Event minecraftEvent) {
                    // actionLine is whatever comes after "api: MY_REWARD " in the YAML
                    int amount = Integer.parseInt(actionLine.trim());
                    player.sendMessage("You received " + amount + " points!");
                    // ... award points logic ...
                }
            },
            new ConditionalEventsAction("SEND_DISCORD") {
                @Override
                public void execute(Player player, String actionLine, Event minecraftEvent) {
                    // e.g., actionLine = "#general Hello from %player%"
                    getLogger().info("Discord: " + actionLine);
                }
            }
        );
    }

    @Override
    public void onDisable() {
        ConditionalEventsAPI.unregisterApiActions(this);
    }

    // Query event state at runtime
    public void exampleQueries(Player player) {
        // Get remaining cooldown time string (e.g., "14s") or "Ready!"
        String cooldown = ConditionalEventsAPI.getEventCooldown(player, "paid_announce");

        // Check whether a one_time event has already been triggered for the player
        String ready = ConditionalEventsAPI.getOneTimeReady(player, "daily_reward"); // "yes" or "no"

        // Check if an event is currently enabled
        boolean enabled = ConditionalEventsAPI.isEventEnabled("paid_announce");
    }
}

```

--------------------------------

### Physics and Visual Effect Actions

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Launch entities directionally or with a specific vector. Spawn fireworks with customizable properties and display particles with specified effects and amounts.

```yaml
- "throw_directional: 2.5"

```

```yaml
- "throw_coordinate: 0;1.5;0"

```

```yaml
- "firework: colors:RED,YELLOW type:BALL power:1 flicker:true trail:false"

```

```yaml
- "particle: effect:FLAME offset:0.5;0.5;0.5 speed:0.01 amount:30"

```

--------------------------------

### Login and Tab-Completion Control

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Prevent players from joining with a custom message or manipulate tab-completion suggestions by clearing, setting, or removing options.

```yaml
- "prevent_join: &cServer is under maintenance."

```

```yaml
- "tab_complete: clear"

```

```yaml
- "tab_complete: set;option1,option2,option3"

```

```yaml
- "tab_complete: remove;gamemode"

```

--------------------------------

### External Integration and API Actions

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Send embeds to Discord via DiscordSRV or call custom actions registered through the API. These actions allow for integration with external services or custom plugin logic.

```yaml
- "discordsrv_embed: channel:general;title:Alert;description:%player% joined"

```

```yaml
- "call_event: my_call_event;%amount%=500;%reason%=vote_reward"

```

```yaml
- "api: MY_CUSTOM_ACTION some_parameter"

```

--------------------------------

### Item Event Types

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Lists trigger types for item-related events, such as interaction, consumption, pickup, and crafting.

```yaml
# Item events
type: item_interact        # player right-clicks with item in hand
type: item_consume         # player eats/drinks item
type: item_pickup
type: item_craft
type: item_drop
type: item_move            # item moves in inventory
type: item_select          # player selects hotbar slot
type: item_enchant
type: item_repair
```

--------------------------------

### Special Event Types

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Includes special trigger types like 'call' for manual invocation and 'custom' for listening to Bukkit events.

```yaml
# Special
type: call                 # manually triggered via /ce call or call_event action
type: custom               # listens for a custom Bukkit event class
```

--------------------------------

### Call Events

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Events that are triggered programmatically via commands, actions, or the Java API, rather than automatic timers.

```APIDOC
## CALL Events

`CALL`-type events have no automatic trigger — they are fired programmatically via the `/ce call` command, the `call_event` action, or the Java `ConditionalEventsCallEvent`.

```yaml
Events:
  give_reward:
    type: call
    conditions:
      - "%amount% > 0"
    actions:
      default:
        - "message: &aYou received &e%amount% coins!"
        - "console_command: eco give %player% %amount%"
```

```bash
# Trigger via command (with optional variables and target player)
/ce call give_reward %amount%=500 player:Steve

# Trigger silently from another action
# In another event's actions:
- "call_event: give_reward;%amount%=100;already_stored"
```
```

--------------------------------

### Third-Party Integration Event Types

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Details trigger types for events originating from third-party plugins like Citizens and WorldGuardEvents.

```yaml
# Third-party integration
type: citizens_right_click_npc          # Citizens plugin
type: wgevents_region_enter             # WorldGuardEvents plugin
type: wgevents_region_leave
type: protocollib_receive_message       # ProtocolLib plugin
```

--------------------------------

### Repetitive Events

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Defines events that trigger automatically at set intervals. `REPETITIVE` fires for each online player, while `REPETITIVE_SERVER` fires once per interval.

```APIDOC
## Repetitive Events

`REPETITIVE` fires for every online player on an interval; `REPETITIVE_SERVER` fires once per interval without a player context.

```yaml
Events:
  auto_gamemode_plotworld:
    type: repetitive
    repetitive_time: 10         # interval in seconds
    conditions:
      - "%player_world% == plotworld"
      - "%player_gamemode% != CREATIVE"
    actions:
      default:
        - "gamemode: CREATIVE"
        - "actionbar: &6Gamemode set to Creative.;100"

  hourly_broadcast:
    type: repetitive_server
    repetitive_time: 3600
    conditions: []
    actions:
      default:
        - "to_all: centered_message: &e&lHourly Reminder: Vote at vote.server.com!"
```
```

--------------------------------

### Message and XP Override Actions

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Override damage dealt, hide default join/leave messages, customize death messages, or set event-specific XP.

```yaml
- "set_damage: 10"

```

```yaml
- "set_damage: 50%"

```

```yaml
- "hide_join_message: true"

```

```yaml
- "hide_leave_message: true"

```

```yaml
- "set_death_message: &c%player% was slain!"

```

```yaml
- "set_event_xp: 0"

```

--------------------------------

### Block Event Types

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Specifies trigger types for block-related events, including interaction, breaking, and placing blocks.

```yaml
# Block events
type: block_interact       # player right-clicks a block
type: block_break
type: block_place
```

--------------------------------

### Combined AND/OR Logic in Conditions

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Combine multiple criteria within a single condition using 'and' or 'or' operators for more complex evaluations.

```yaml
  # AND / OR within a single condition line
  - "%player_world% == world or %player_world% == world_nether"
  - "%player_level% >= 10 and %vault_eco_balance% >= 500"
```

--------------------------------

### Teleportation and Potion Effects

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Teleport players to specific coordinates or apply/remove potion effects. Potion effects can be configured with duration, level, and particle options.

```yaml
- "teleport: world;100;64;200;0;0"

```

```yaml
- "give_potion_effect: SPEED;200;2;true;false"

```

```yaml
- "remove_potion_effect: SPEED"

```

--------------------------------

### Player State Modification Actions

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Modify player health, food levels, or apply effects like freezing. Inventory can be closed or cleared.

```yaml
- "damage: 5"

```

```yaml
- "heal: 4"

```

```yaml
- "set_food_level: 20"

```

```yaml
- "freeze: 60"

```

```yaml
- "close_inventory: true"

```

```yaml
- "clear_inventory: true"

```

--------------------------------

### Action Group Execution

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Execute a randomly-weighted action group, allowing for varied outcomes based on defined probabilities. This is useful for implementing loot tables or randomized rewards.

```yaml
- "execute_action_group: reward_common:70;reward_rare:25;reward_epic:5"

```

--------------------------------

### Call Events Triggered Programmatically

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

CALL events are not automatically triggered and must be fired via commands, actions, or the Java API. Conditions can filter when the event is executed.

```yaml
Events:
  give_reward:
    type: call
    conditions:
      - "%amount% > 0"
    actions:
      default:
        - "message: &aYou received &e%amount% coins!"
        - "console_command: eco give %player% %amount%"

```

--------------------------------

### ConditionalEventsEvent Listener

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Listen to the ConditionalEventsEvent when an event's conditions are met and an action group is about to run. This is useful for auditing or extending plugin behavior.

```APIDOC
## ConditionalEventsEvent Listener

### Description
Fired every time an event's conditions are satisfied and an action group is about to run. Useful for auditing or extending behavior.

### Method Signature
`onCEEvent(ConditionalEventsEvent event)`

### Parameters
- **event** (ConditionalEventsEvent) - The event object containing details about the triggered event.
  - `getEvent()`: Returns the name of the ConditionalEvents event.
  - `getActionGroup()`: Returns the name of the action group being executed.
  - `getPlayer()`: Returns the player associated with the event, or null for server-scope events.

### Example Usage
```java
import ce.ajneb97.api.ConditionalEventsEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class CEListener implements Listener {

    @EventHandler
    public void onCEEvent(ConditionalEventsEvent event) {
        String eventName   = event.getEvent();       // ConditionalEvents event name
        String actionGroup = event.getActionGroup(); // "default", "cooldown", custom name, etc.
        // event.getPlayer() may be null for server-scope events
        if (event.getPlayer() != null) {
            event.getPlayer().sendMessage("[Audit] " + eventName + " → " + actionGroup);
        }
    }
}
```
```

--------------------------------

### Fire ConditionalEventsCallEvent Programmatically in Java

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Trigger a CALL-type event from your Java code. Allows programmatic execution of event actions, optionally with custom variables.

```java
import ce.ajneb97.api.ConditionalEventsCallEvent;
import ce.ajneb97.model.StoredVariable;
import org.bukkit.Bukkit;
import org.bukkit.entity.Player;
import java.util.ArrayList;

// Fire a CALL-type event from Java code
Player target = Bukkit.getPlayer("Steve");
ArrayList<StoredVariable> vars = new ArrayList<>();
vars.add(new StoredVariable("%amount%", "750"));
vars.add(new StoredVariable("%reason%", "vote"));

ConditionalEventsCallEvent callEvent = new ConditionalEventsCallEvent(target, vars, "give_reward");
Bukkit.getPluginManager().callEvent(callEvent);
```

--------------------------------

### ConditionalEventsCallEvent Programmatic Firing

Source: https://context7.com/ajneb97/conditionalevents/llms.txt

Programmatically fire a CALL-type event using the ConditionalEventsCallEvent. This allows triggering custom event chains from your own Java code.

```APIDOC
## ConditionalEventsCallEvent Programmatic Firing

### Description
Fire a CALL-type event from Java code. This allows you to trigger custom event sequences defined within the ConditionalEvents plugin.

### Method Signature
`new ConditionalEventsCallEvent(Player target, ArrayList<StoredVariable> vars, String eventName)`

### Parameters
- **target** (Player) - The player for whom the event should be fired. Can be null.
- **vars** (ArrayList<StoredVariable>) - A list of variables to pass to the event. Each `StoredVariable` has a `%name%` and a `value`.
- **eventName** (String) - The name of the CALL event to fire.

### Example Usage
```java
import ce.ajneb97.api.ConditionalEventsCallEvent;
import ce.ajneb97.model.StoredVariable;
import org.bukkit.Bukkit;
import org.bukkit.entity.Player;
import java.util.ArrayList;

// Fire a CALL-type event from Java code
Player target = Bukkit.getPlayer("Steve");
ArrayList<StoredVariable> vars = new ArrayList<>();
vars.add(new StoredVariable("%amount%", "750"));
vars.add(new StoredVariable("%reason%", "vote"));

ConditionalEventsCallEvent callEvent = new ConditionalEventsCallEvent(target, vars, "give_reward");
Bukkit.getPluginManager().callEvent(callEvent);
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.