Custom Events

Overview

Hubbly provides custom Bukkit events that developers can listen to for extending functionality or integrating with other plugins. All events are cancellable and follow standard Bukkit event patterns.

All Hubbly events extend org.bukkit.event.Event and implement Cancellable, allowing developers to prevent default behavior by calling setCancelled(true).

ActionEvent

Triggered when a Hubbly action is about to be executed. Actions are the core of Hubbly’s interactive system, used in menus, items, and configuration.

Event Properties

player

Player

required

The player who triggered the action.

action

Action

required

The Action object being executed. Use getActionIdentifier() to get the action type as a string.

actionData

String

required

The data/parameters passed to the action. Format varies by action type.

cancelled

boolean

default:"false"

Whether the event is cancelled. If true, the action will not execute.

Available Methods

getPlayer()

Player

Returns the player who triggered this action.

getActionIdentifier()

String

Returns the identifier of the action (e.g., “PLAYER”, “SOUND”, “MESSAGE”).

getActionData()

String

Returns the data string passed to the action.

isCancelled()

boolean

Returns whether this event is cancelled.

setCancelled(boolean)

void

Set whether this event should be cancelled.

Usage Example

import me.calrl.hubbly.events.ActionEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class CustomListener implements Listener {
    
    @EventHandler
    public void onAction(ActionEvent event) {
        // Get event information
        Player player = event.getPlayer();
        String actionType = event.getActionIdentifier();
        String actionData = event.getActionData();
        
        // Log the action
        plugin.getLogger().info(player.getName() + " executed: " + actionType);
        
        // Cancel specific actions
        if (actionType.equals("BUNGEE") && !player.hasPermission("hub.bungee")) {
            event.setCancelled(true);
            player.sendMessage("You don't have permission to change servers!");
        }
    }
}

Action Types

The following action identifiers are available in Hubbly:

Available Action Types

PLAYER

action

Executes a command as the player.Format: [PLAYER] commandExample: [PLAYER] spawn

CONSOLE

action

Executes a command from the console.Format: [CONSOLE] commandExample: [CONSOLE] give %player% diamond 1

MESSAGE

action

Sends a message to the player.Format: [MESSAGE] textExample: [MESSAGE] &aWelcome to the hub!

BROADCAST

action

Broadcasts a message to all players.Format: [BROADCAST] textExample: [BROADCAST] &e%player% &7found a secret!

SOUND

action

Plays a sound to the player.Format: [SOUND] sound_nameExample: [SOUND] ENTITY_PLAYER_LEVELUP

TITLE

action

Displays a title to the player.Format: [TITLE] title;subtitle;fadeIn;stay;fadeOutExample: [TITLE] &aWelcome!;&7Enjoy your stay;10;70;20

GAMEMODE

action

Changes the player’s game mode.Format: [GAMEMODE] modeExample: [GAMEMODE] CREATIVE

FIREWORK

action

Spawns a firework at the player’s location.Format: [FIREWORK]

EFFECT

action

Applies a potion effect to the player.Format: [EFFECT] effect:duration:amplifierExample: [EFFECT] SPEED:200:1

ITEM

action

Gives an item to the player.Format: [ITEM] item_idExample: [ITEM] custom_item_1

LAUNCH

action

Launches the player into the air.Format: [LAUNCH] x,y,zExample: [LAUNCH] 0,2,0

BUNGEE

action

Sends the player to another BungeeCord server.Format: [BUNGEE] server_nameExample: [BUNGEE] lobby-2

Opens a custom menu for the player.Format: [MENU] menu_idExample: [MENU] selector

LINK

action

Sends a clickable link to the player.Format: [LINK] urlExample: [LINK] https://example.com

action

Closes the player’s currently open inventory.Format: [CLOSE]

CLEAR

action

Clears the player’s inventory.Format: [CLEAR]

SLOT

action

Gives an item to a specific inventory slot.Format: [SLOT] slot:item_idExample: [SLOT] 4:compass

HubblySpawnEvent

Triggered when a player is being teleported to the hub spawn location.

Event Properties

player

Player

required

The player being teleported to spawn.

location

Location

required

The spawn location the player will be teleported to.

cancelled

boolean

default:"false"

Whether the event is cancelled. If true, the teleport will not occur.

Available Methods

getPlayer()

Player

Returns the player being teleported.

getLocation()

Location

Returns the spawn location.

isCancelled()

boolean

Returns whether this event is cancelled.

setCancelled(boolean)

void

Set whether this event should be cancelled.

Usage Example

import me.calrl.hubbly.events.HubblySpawnEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class SpawnListener implements Listener {
    
    @EventHandler
    public void onHubblySpawn(HubblySpawnEvent event) {
        Player player = event.getPlayer();
        Location spawnLocation = event.getLocation();
        
        // Log spawn teleports
        plugin.getLogger().info(player.getName() + " is spawning at: " + 
            spawnLocation.getBlockX() + ", " + 
            spawnLocation.getBlockY() + ", " + 
            spawnLocation.getBlockZ());
        
        // Prevent spawning in certain conditions
        if (player.hasMetadata("in_event")) {
            event.setCancelled(true);
            player.sendMessage("You cannot spawn while in an event!");
        }
        
        // Apply effects on spawn
        if (!event.isCancelled()) {
            player.setHealth(20.0);
            player.setFoodLevel(20);
            player.getInventory().clear();
        }
    }
}

When It’s Called

The HubblySpawnEvent is triggered:

When a player executes /spawn
When a player joins the server (if configured)
When Hubbly programmatically sends a player to spawn

Event Registration

To listen to Hubbly events in your plugin, register your listener class:

import org.bukkit.plugin.java.JavaPlugin;

public class YourPlugin extends JavaPlugin {
    
    @Override
    public void onEnable() {
        // Register your event listener
        getServer().getPluginManager().registerEvents(
            new CustomListener(), 
            this
        );
    }
}

Event Priorities

You can control when your listener runs relative to other listeners using event priorities:

import org.bukkit.event.EventPriority;

@EventHandler(priority = EventPriority.HIGH)
public void onAction(ActionEvent event) {
    // This runs after NORMAL priority listeners
}

Priority Levels

LOWEST - Runs first
LOW - Runs early
NORMAL - Default priority (most listeners)
HIGH - Runs late
HIGHEST - Runs last
MONITOR - Read-only, runs after everything (don’t modify events here)

Best Practices

Event Handling Tips

Don’t Cancel Unnecessarily

Only cancel events when you have a good reason. Cancelling events can break other plugins’ functionality.

Use Appropriate Priorities

Use LOWEST if you need to modify event data before others
Use NORMAL for most cases
Use HIGH if you want to override others’ decisions
Use MONITOR only for logging/tracking (never modify)

Check for Cancellation

@EventHandler
public void onAction(ActionEvent event) {
    if (event.isCancelled()) {
        return; // Don't process cancelled events
    }
    // Your logic here
}

Handle Exceptions

Wrap your event logic in try-catch to prevent breaking other plugins:

@EventHandler
public void onAction(ActionEvent event) {
    try {
        // Your logic here
    } catch (Exception e) {
        plugin.getLogger().warning("Error handling action: " + e.getMessage());
    }
}

Common Use Cases

Logging Player Actions

@EventHandler
public void onAction(ActionEvent event) {
    String log = String.format("%s executed action %s with data: %s",
        event.getPlayer().getName(),
        event.getActionIdentifier(),
        event.getActionData());
    plugin.getLogger().info(log);
}

Custom Permission Checks

@EventHandler
public void onAction(ActionEvent event) {
    String actionType = event.getActionIdentifier();
    Player player = event.getPlayer();
    
    if (actionType.equals("GAMEMODE")) {
        if (!player.hasPermission("custom.gamemode")) {
            event.setCancelled(true);
            player.sendMessage("No permission!");
        }
    }
}

Modifying Spawn Location

@EventHandler
public void onSpawn(HubblySpawnEvent event) {
    Player player = event.getPlayer();
    
    // VIP players spawn at a different location
    if (player.hasPermission("hub.vip")) {
        event.setCancelled(true);
        Location vipSpawn = new Location(player.getWorld(), 100, 64, 100);
        player.teleport(vipSpawn);
    }
}

Integration with Other Plugins

@EventHandler
public void onAction(ActionEvent event) {
    // Award points when players use actions
    if (event.getActionIdentifier().equals("BUNGEE")) {
        PointsAPI.givePoints(event.getPlayer(), 10);
    }
}

Commands

Actions

Permissions

Events

Overview

ActionEvent

Event Properties

Available Methods

Usage Example

Action Types

HubblySpawnEvent

Event Properties

Available Methods

Usage Example

When It’s Called

Event Registration

Event Priorities

Priority Levels

Best Practices

Don’t Cancel Unnecessarily

Use Appropriate Priorities

Check for Cancellation

Handle Exceptions

Common Use Cases

Logging Player Actions

Custom Permission Checks

Modifying Spawn Location

Integration with Other Plugins

Build docs developers (and LLMs) love

Commands

Actions

Permissions

Events

​Overview

​ActionEvent

​Event Properties

​Available Methods

​Usage Example

​Action Types

​HubblySpawnEvent

​Event Properties

​Available Methods

​Usage Example

​When It’s Called

​Event Registration

​Event Priorities

​Priority Levels

​Best Practices

​Don’t Cancel Unnecessarily

​Use Appropriate Priorities

​Check for Cancellation

​Handle Exceptions

​Common Use Cases

​Logging Player Actions

​Custom Permission Checks

​Modifying Spawn Location

​Integration with Other Plugins

Build docs developers (and LLMs) love

Overview

ActionEvent

Event Properties

Available Methods

Usage Example

Action Types

HubblySpawnEvent

Event Properties

Available Methods

Usage Example

When It’s Called

Event Registration

Event Priorities

Priority Levels

Best Practices

Don’t Cancel Unnecessarily

Use Appropriate Priorities

Check for Cancellation

Handle Exceptions

Common Use Cases

Logging Player Actions

Custom Permission Checks

Modifying Spawn Location

Integration with Other Plugins