The "registerListener" API

The registerListener function allows you to register event listeners in your scripts to respond to Bukkit events in real-time. This is essential for creating dynamic gameplay mechanics, responding to player actions, and integrating with the server lifecycle.

Registering event listeners with registerListener(eventClass, callback, optionalEventPriority? )

Registers a callback function that will be invoked whenever the specified Bukkit event is fired. The callback receives the event object as its parameter, giving you full access to event data and methods.

Parameters:

• eventClass - The Bukkit event class you want to listen to (e.g., $.PlayerJoinEvent, $.BlockBreakEvent)
• callback - A function that will be called when the event fires, receiving the event object as a parameter
• optionalEventPriority (optional) - The priority level for this listener (defaults to $.EventPriority.NORMAL)

// Listen for player join events
registerListener($.PlayerJoinEvent, (event) => {
    const player = event.getPlayer();
    player.sendMessage('Welcome to the server!');
});

Event Priority

You can optionally specify the priority of your event listener using the third parameter. Event priorities determine the order in which listeners are called, which is important when multiple plugins or scripts handle the same event.

Available priorities (in order of execution):

• $.EventPriority.LOWEST
• $.EventPriority.LOW
• $.EventPriority.NORMAL (default)
• $.EventPriority.HIGH
• $.EventPriority.HIGHEST
• $.EventPriority.MONITOR

// Register a high-priority listener to modify the event early
registerListener($.PlayerSpawnLocationEvent, (event) => {
    const player = event.getPlayer();
    
    if (player.hasPermission('admin.spawn')) {
        event.setSpawnLocation(adminSpawn);
    }
}, $.EventPriority.HIGH);

Practical Examples

Setting spawn locations based on permissions

const spawn = newLocation('world', -57.5, 65.5, -1542.5);
const vip_spawn = newLocation('world', -57.5, 71, -1008.5);

registerListener($.PlayerSpawnLocationEvent, (event) => {
    if (event.getPlayer().hasPermission('dc.spawn.bypass')) {
        return;
    }

    if (event.getPlayer().hasPermission('dc.spawn.vip')) {
        event.setSpawnLocation(vip_spawn);
        return;
    }

    event.setSpawnLocation(spawn);
});

Creating a custom join message system

registerListener($.PlayerJoinEvent, (event) => {
    const player = event.getPlayer();
    
    // Suppress default join message
    event.setJoinMessage(null);
    
    // Send custom message to all players
    const customMessage = `§6${player.getName()} §ehas entered the server! `;
    $.Bukkit.broadcastMessage(customMessage);
});

Preventing block breaking in protected areas

const protectedZone = {
    minX: -100, maxX: 100,
    minZ: -100, maxZ: 100
};

registerListener($.BlockBreakEvent, (event) => {
    const block = event.getBlock();
    const loc = block.getLocation();
    
    const x = loc.getX();
    const z = loc.getZ();
    
    if (x >= protectedZone.minX && x <= protectedZone.maxX &&
        z >= protectedZone.minZ && z <= protectedZone.maxZ) {
        event.setCancelled(true);
        event.getPlayer().sendMessage('§cYou cannot break blocks in this protected area!');
    }
});

Automatic Cleanup

Event listeners registered through registerListener are automatically unregistered when your script is unloaded or reloaded. This prevents memory leaks and ensures that old listeners don't continue firing after a script update.

You don't need to manually unregister listeners - the script runtime handles this for you during the cleanup phase.

Working with Event Cancellation

Many Bukkit events are cancellable, meaning you can prevent the default action from occurring. Always check if an event is cancellable before attempting to cancel it.

registerListener($.PlayerInteractEvent, (event) => {
    const player = event.getPlayer();
    const item = event.getItem();
    
    if (item && item.getType().toString() === 'DIAMOND') {
        event.setCancelled(true);
        player.sendMessage('§cYou cannot use diamonds here!');
    }
});

Using custom events

Use Script.loadClass() to import events not already available through the $ shorthand:

const CustomPluginEvent = Script.loadClass('com.example.plugin.events.CustomPluginEvent');

registerListener(CustomPluginEvent, (event) => {
    console.log('Custom event fired!');
});