Skip to main content

​
Overview

The Trigger API allows you to create custom event handlers that trigger popup displays and HUD updates. Triggers connect in-game events to BetterHud components.

​
HudTrigger Interface

The HudTrigger<T> interface represents a trigger that responds to events of type T.

​
Package

kr.toxicity.hud.api.trigger.HudTrigger

​
Type Parameters

​
T
Type
The type of event this trigger handles (e.g., PlayerEvent, DamageEvent, etc.)

​
Methods

​
getKey

Gets a unique key for the given event instance. 
@NotNull Object getKey(T t)
​
t
T
required
The event instance to get the key for
​
return
Object
A unique identifier for this event (normally a random UUID or event-specific identifier)

​
registerEvent

Registers an event handler for this trigger. 
void registerEvent(@NotNull BiConsumer<UUID, UpdateEvent> eventConsumer)
​
eventConsumer
BiConsumer<UUID, UpdateEvent>
required
A consumer that handles trigger events. Receives the player UUID and the update event.

​
UpdateEvent Interface

Represents the context for an update triggered by an event.

​
Package

kr.toxicity.hud.api.update.UpdateEvent

​
Methods

​
getType

Gets the reason for this update. 
@NotNull UpdateReason getType()
​
return
UpdateReason
The type of update that occurred

​
getKey

Gets the unique key for this event. 
@NotNull Object getKey()
​
return
Object
A unique identifier for this update event (normally a UUID)

​
source

Gets the source event that caused this update. 
default @NotNull UpdateEvent source()
​
return
UpdateEvent
The original event that triggered this update (returns this by default)

​
Empty Event

UpdateEvent EMPTY
A static empty event instance for cases where no specific trigger is needed.

​
Usage Examples

​
Creating a Custom Trigger

import kr.toxicity.hud.api.trigger.HudTrigger;
import kr.toxicity.hud.api.update.UpdateEvent;
import org.bukkit.event.player.PlayerEvent;

import java.util.UUID;
import java.util.function.BiConsumer;

public class CustomPlayerTrigger implements HudTrigger<PlayerEvent> {
    
    @Override
    public Object getKey(PlayerEvent event) {
        // Use player UUID as the key
        return event.getPlayer().getUniqueId();
    }
    
    @Override
    public void registerEvent(BiConsumer<UUID, UpdateEvent> eventConsumer) {
        // This would typically be called by BetterHud's internal systems
        // to register the handler that shows popups/updates HUDs
    }
}

​
Working with Bukkit Event Triggers

import kr.toxicity.hud.api.bukkit.trigger.HudBukkitEventTrigger;
import org.bukkit.event.Event;
import org.bukkit.event.player.PlayerMoveEvent;
import org.bukkit.plugin.Plugin;

public class BukkitTriggerExample {
    
    public void setupTrigger(Plugin plugin) {
        // Create a trigger for player movement
        HudBukkitEventTrigger<PlayerMoveEvent> moveTrigger = 
            new HudBukkitEventTrigger<>(plugin, PlayerMoveEvent.class);
        
        // The trigger will automatically listen to the event
        // and forward it to registered popup/HUD handlers
    }
}

​
Using UpdateEvent with Popups

import kr.toxicity.hud.api.popup.Popup;
import kr.toxicity.hud.api.popup.PopupUpdater;
import kr.toxicity.hud.api.update.UpdateEvent;
import kr.toxicity.hud.api.player.HudPlayer;
import org.bukkit.entity.Player;

public void showPopupWithEvent(Player bukkitPlayer, Popup popup, UpdateEvent event) {
    HudPlayer hudPlayer = BetterHud.inst().getBootstrap().player(bukkitPlayer.getUniqueId());
    if (hudPlayer == null) return;
    
    // Show popup with the update event context
    PopupUpdater updater = popup.show(event, hudPlayer);
    if (updater != null) {
        bukkitPlayer.sendMessage("Popup triggered by: " + event.getType());
    }
}

​
Creating a Damage Trigger

import kr.toxicity.hud.api.trigger.HudTrigger;
import kr.toxicity.hud.api.update.UpdateEvent;
import kr.toxicity.hud.api.update.UpdateReason;
import org.bukkit.entity.Player;
import org.bukkit.event.entity.EntityDamageEvent;
import org.jetbrains.annotations.NotNull;

import java.util.UUID;
import java.util.function.BiConsumer;

public class DamageTrigger implements HudTrigger<EntityDamageEvent> {
    private BiConsumer<UUID, UpdateEvent> handler;
    
    @Override
    public @NotNull Object getKey(EntityDamageEvent event) {
        // Generate unique key for each damage event
        return UUID.randomUUID();
    }
    
    @Override
    public void registerEvent(@NotNull BiConsumer<UUID, UpdateEvent> eventConsumer) {
        this.handler = eventConsumer;
    }
    
    public void onDamage(EntityDamageEvent event) {
        if (!(event.getEntity() instanceof Player player)) return;
        if (handler == null) return;
        
        // Create update event
        UpdateEvent updateEvent = new UpdateEvent() {
            @Override
            public @NotNull UpdateReason getType() {
                return UpdateReason.EMPTY; // Or create custom reason
            }
            
            @Override
            public @NotNull Object getKey() {
                return getKey(event);
            }
        };
        
        // Trigger the handler
        handler.accept(player.getUniqueId(), updateEvent);
    }
}

​
Trigger with Custom Variables

import kr.toxicity.hud.api.BetterHud;
import kr.toxicity.hud.api.player.HudPlayer;
import kr.toxicity.hud.api.popup.Popup;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerLevelChangeEvent;

public class LevelUpTrigger implements Listener {
    
    @EventHandler
    public void onLevelUp(PlayerLevelChangeEvent event) {
        Player player = event.getPlayer();
        HudPlayer hudPlayer = BetterHud.inst().getBootstrap().player(player.getUniqueId());
        if (hudPlayer == null) return;
        
        // Set variables for the popup
        hudPlayer.getVariableMap().put("old_level", String.valueOf(event.getOldLevel()));
        hudPlayer.getVariableMap().put("new_level", String.valueOf(event.getNewLevel()));
        
        // Get and show the level up popup
        Popup levelPopup = BetterHud.inst().getPopupManager().getPopup("level_up");
        if (levelPopup != null) {
            levelPopup.show(UpdateEvent.EMPTY, hudPlayer);
        }
    }
}

​
Conditional Trigger System

import kr.toxicity.hud.api.trigger.HudTrigger;
import kr.toxicity.hud.api.update.UpdateEvent;
import org.bukkit.event.Event;

import java.util.UUID;
import java.util.function.BiConsumer;
import java.util.function.Predicate;

public class ConditionalTrigger<T extends Event> implements HudTrigger<T> {
    private final Predicate<T> condition;
    private BiConsumer<UUID, UpdateEvent> handler;
    
    public ConditionalTrigger(Predicate<T> condition) {
        this.condition = condition;
    }
    
    @Override
    public Object getKey(T event) {
        return UUID.randomUUID();
    }
    
    @Override
    public void registerEvent(BiConsumer<UUID, UpdateEvent> eventConsumer) {
        this.handler = eventConsumer;
    }
    
    public void handleEvent(T event, UUID playerUuid, UpdateEvent updateEvent) {
        // Only trigger if condition is met
        if (condition.test(event) && handler != null) {
            handler.accept(playerUuid, updateEvent);
        }
    }
}

// Usage:
// ConditionalTrigger<PlayerMoveEvent> trigger = new ConditionalTrigger<>(
//     event -> event.getTo().getY() < 0  // Trigger when player falls below Y=0
// );

​
Multi-Event Trigger

import kr.toxicity.hud.api.popup.Popup;
import kr.toxicity.hud.api.player.HudPlayer;
import kr.toxicity.hud.api.BetterHud;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;
import org.bukkit.event.player.PlayerQuitEvent;

public class MultiEventTrigger implements Listener {
    private final String popupName;
    
    public MultiEventTrigger(String popupName) {
        this.popupName = popupName;
    }
    
    @EventHandler
    public void onJoin(PlayerJoinEvent event) {
        showPopup(event.getPlayer(), "join");
    }
    
    @EventHandler
    public void onQuit(PlayerQuitEvent event) {
        showPopup(event.getPlayer(), "quit");
    }
    
    private void showPopup(Player player, String eventType) {
        HudPlayer hudPlayer = BetterHud.inst().getBootstrap().player(player.getUniqueId());
        if (hudPlayer == null) return;
        
        // Set event type variable
        hudPlayer.getVariableMap().put("event_type", eventType);
        
        Popup popup = BetterHud.inst().getPopupManager().getPopup(popupName);
        if (popup != null) {
            popup.show(UpdateEvent.EMPTY, hudPlayer);
        }
    }
}
  • Popup API - Triggers are commonly used to show popups
  • Placeholders - Use with triggers to display dynamic data
  • Events - Bukkit event integration

​
See Also

  • HudTrigger interface: kr.toxicity.hud.api.trigger.HudTrigger
  • UpdateEvent interface: kr.toxicity.hud.api.update.UpdateEvent
  • HudBukkitEventTrigger: kr.toxicity.hud.api.bukkit.trigger.HudBukkitEventTrigger
  • UpdateReason enum: kr.toxicity.hud.api.update.UpdateReason

Build docs developers (and LLMs) love

Get started for freeTalk to us