> For the complete documentation index, see [llms.txt](https://buildsystem.eintosti.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://buildsystem.eintosti.de/developer-portal/event-pipeline.md).

# Event Pipeline

The events BuildSystem fires, and how to cancel them.

BuildSystem fires custom Bukkit events under `de.eintosti.buildsystem.api.event` allowing plugins to intercept lifecycle stages, audit player actions, or prevent world mutations.

***

## 1. World Lifecycle Events (`event.world`)

Listen to world events to hook into creation, load, unload, rename, or deletion tasks. Every event in this table except `BuildWorldCreateEvent` and `PlayerBuildModeToggleEvent` extends `BuildWorldEvent` and exposes the world through `getBuildWorld()`.

| Event Class                   | Cancellable | Description                                                                                                                                                                                                   |
| ----------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BuildWorldCreateEvent`       | **Yes**     | Fired before a new world is generated or imported. The world does not exist yet, so it exposes `getWorldName()`, `getType()`, `getCreator()` and `isImport()` instead of a `BuildWorld`.                      |
| `BuildWorldPostCreateEvent`   | No          | Fired once the Bukkit world exists after a successful generation or import, and not at all when generation fails. `isImport()` tells the two apart.                                                           |
| `BuildWorldDeleteEvent`       | **Yes**     | Fired before a world directory is deleted. Cancelling it makes `WorldService#deleteWorld` fail with `WorldDeletionCancelledException`; tell the player yourself.                                              |
| `BuildWorldPostDeleteEvent`   | No          | Fired on the main thread after the world directory is deleted. The world is no longer registered, so only read from it.                                                                                       |
| `BuildWorldLoadEvent`         | **Yes**     | Fired before a world is loaded into server memory.                                                                                                                                                            |
| `BuildWorldPostLoadEvent`     | No          | Fired after a world is loaded.                                                                                                                                                                                |
| `BuildWorldUnloadEvent`       | **Yes**     | Fired before a loaded world is unloaded from server memory. Cancelling it also stops a delete, rename, restore or unimport of that world, which then reports that the world could not be unloaded.            |
| `BuildWorldPostUnloadEvent`   | No          | Fired after a world is unloaded.                                                                                                                                                                              |
| `BuildWorldUnimportEvent`     | No          | Fired when a world is removed from the plugin registry without deleting its directory. Also fired during a deletion, once the world is unloaded and before its directory is deleted.                          |
| `BuildWorldRenameEvent`       | No          | Fired after a world is renamed. `getOldName()` and `getNewName()` give both names; `getBuildWorld().getName()` already returns the new one.                                                                   |
| `BuildWorldStatusChangeEvent` | No          | Fired when a world's status actually changes, with `getPreviousStatus()` and `getNewStatus()`.                                                                                                                |
| `BuildWorldManipulationEvent` | **Yes**     | Fired when a player places, breaks or interacts with blocks in a build world. It wraps the Bukkit event that caused it (`getParentEvent()`), and cancelling one cancels the other.                            |
| `PlayerBuildModeToggleEvent`  | **Yes**     | Fired when `/build` turns a player's build mode on or off. `isBuildMode()` is the new state and `getCauser()` the player who ran the command. Not fired by `PlayerService#enterBuildMode` / `leaveBuildMode`. |

### Example Listener: Auditing Creation Events

```java
import de.eintosti.buildsystem.api.event.world.BuildWorldCreateEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class WorldAuditListener implements Listener {

    @EventHandler
    public void onWorldCreate(BuildWorldCreateEvent event) {
        String worldName = event.getWorldName();
        
        // Prevent creation of restricted naming layouts
        if (worldName.startsWith("test_")) {
            event.setCancelled(true);
        }
    }
}
```

***

## 2. Folder Events (`event.folder`)

React when folders are registered or removed from the system. Both events expose the folder through `getFolder()`.

| Event Class          | Cancellable | Description                                                               |
| -------------------- | ----------- | ------------------------------------------------------------------------- |
| `FolderCreatedEvent` | No          | Fired after a new world folder is created.                                |
| `FolderDeletedEvent` | No          | Fired after a folder is deleted, once for each subfolder removed with it. |

***

## 3. Backup Events (`event.backup`)

Track archiving, uploads, and restorations. Each event exposes `getBuildWorld()` and `getBackup()`, and fires on the main thread.

| Event Class           | Cancellable | Description                                                                                                |
| --------------------- | ----------- | ---------------------------------------------------------------------------------------------------------- |
| `BackupCreatedEvent`  | No          | Fired after a backup is successfully generated and archived.                                               |
| `BackupDeletedEvent`  | No          | Fired after a backup is deleted from storage, including the oldest backups removed by the per-world limit. |
| `BackupRestoredEvent` | No          | Fired after a backup is restored to a world.                                                               |
