Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/BG-Software-LLC/SuperiorSkyblock2/llms.txt

Use this file to discover all available pages before exploring further.

SuperiorSkyblock2 provides a comprehensive event system with over 110 events that allow developers to hook into nearly every aspect of island functionality, player actions, and plugin lifecycle.

​
Event Categories

Events are organized into the following categories:
  • Island Events - Island lifecycle, configuration, and management events
  • Player Events - Player-specific actions and state changes
  • Block Events - Block stacking and manipulation events
  • Mission Events - Mission completion and progress tracking
  • Plugin Events - Plugin initialization and data loading

​
Base Event Classes

​
IslandEvent

All island-related events extend from IslandEvent, which provides: 
public abstract class IslandEvent extends Event {
    protected final Island island;
    
    public Island getIsland() {
        return island;
    }
}
IslandEvent automatically handles async event execution when called from non-primary threads.

​
Listening to Events

​
Basic Event Listener

import com.bgsoftware.superiorskyblock.api.events.*;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class MyEventListener implements Listener {
    
    @EventHandler
    public void onIslandCreate(IslandCreateEvent event) {
        Island island = event.getIsland();
        SuperiorPlayer player = event.getPlayer();
        String schematic = event.getSchematic();
        
        // Your custom logic here
        if (event.canTeleport()) {
            player.asPlayer().sendMessage("Welcome to your new island!");
        }
    }
}

​
Cancellable Events

Many events implement Cancellable, allowing you to prevent actions: 
@EventHandler
public void onIslandDisband(IslandDisbandEvent event) {
    Island island = event.getIsland();
    
    // Prevent disbanding islands with high worth
    if (island.getWorth().compareTo(BigDecimal.valueOf(1000000)) > 0) {
        event.setCancelled(true);
        event.getPlayer().asPlayer().sendMessage(
            "Cannot disband an island worth over 1 million!"
        );
    }
}

​
Priority and Async Handling

import org.bukkit.event.EventPriority;

@EventHandler(priority = EventPriority.HIGH)
public void onIslandWorthCalculated(IslandWorthCalculatedEvent event) {
    // This event is called asynchronously when calculated off the main thread
    Island island = event.getIsland();
    BigDecimal level = event.getLevel();
    BigDecimal worth = event.getWorth();
    
    // Store data or trigger notifications
}
Events that extend IslandEvent are automatically marked as async when not called from the primary thread. Be careful when accessing Bukkit API from async events.

​
Event Registration

Register your listener in your plugin’s onEnable() method: 
@Override
public void onEnable() {
    getServer().getPluginManager().registerEvents(
        new MyEventListener(), 
        this
    );
}

​
Common Event Patterns

​
Pre and Post Events

Some operations have both pre and post events: 
@EventHandler
public void onPreIslandCreate(PreIslandCreateEvent event) {
    // Called before island creation
    // Can be cancelled to prevent creation
}

@EventHandler
public void onPostIslandCreate(PostIslandCreateEvent event) {
    // Called after island is fully created
    // Cannot be cancelled
}

​
Enter and Leave Events

@EventHandler
public void onIslandEnter(IslandEnterEvent event) {
    SuperiorPlayer player = event.getPlayer();
    Island island = event.getIsland();
    EnterCause cause = event.getCause();
    
    // Customize behavior based on enter cause
    switch (cause) {
        case PLAYER_MOVE:
            // Player walked into island
            break;
        case PLAYER_TELEPORT:
            // Player teleported to island
            break;
        case PORTAL:
            // Player used portal
            break;
    }
    
    // Set custom teleport location if cancelled
    if (someCondition) {
        event.setCancelTeleport(customLocation);
        event.setCancelled(true);
    }
}

​
Change Events

Many “Change” events allow you to modify or cancel configuration changes: 
@EventHandler
public void onIslandChangeBorderSize(IslandChangeBorderSizeEvent event) {
    int oldSize = event.getIsland().getIslandSize();
    int newSize = event.getBorderSize();
    
    // Enforce maximum border size
    if (newSize > 500) {
        event.setBorderSize(500);
    }
}

​
Event Flow Examples

​
Island Creation Flow

  1. PreIslandCreateEvent (cancellable)
  2. Island object is created
  3. IslandCreateEvent (cancellable)
  4. Schematic is pasted
  5. IslandSchematicPasteEvent
  6. PostIslandCreateEvent

​
Island Worth Calculation Flow

  1. Worth calculation starts
  2. Blocks are scanned
  3. IslandWorthCalculatedEvent (async)
  4. IslandWorthUpdateEvent

​
Best Practices

  • Check for null: Some events have nullable fields (e.g., @Nullable SuperiorPlayer when console executes commands)
  • Use appropriate priorities: Use EventPriority.LOW for early checks, EventPriority.HIGH for final modifications
  • Avoid heavy operations in events: Events are called frequently; cache data when possible
  • Handle async events safely: Many island calculation events run async; avoid direct Bukkit API calls

​
Thread Safety

@EventHandler
public void onIslandWorthCalculated(IslandWorthCalculatedEvent event) {
    // This may be async - schedule sync task for Bukkit API calls
    Bukkit.getScheduler().runTask(plugin, () -> {
        // Safe to use Bukkit API here
        event.getIsland().sendMessage("Worth calculated!");
    });
}

​
Next Steps

​
Additional Resources

For the complete list of all 110+ events, browse the source code or use your IDE’s autocomplete with the com.bgsoftware.superiorskyblock.api.events package.

Build docs developers (and LLMs) love

Get started for freeTalk to us