> 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/v4/developer-portal/event-pipeline.md).

# Event Pipeline

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.

| Event Class                   | Cancellable | Description                                                                    |
| ----------------------------- | ----------- | ------------------------------------------------------------------------------ |
| `BuildWorldCreateEvent`       | **Yes**     | Fired before a new world is generated or imported.                             |
| `BuildWorldPostCreateEvent`   | No          | Fired after world generation/import successfully completes.                    |
| `BuildWorldDeleteEvent`       | **Yes**     | Fired before a world directory is deleted.                                     |
| `BuildWorldPostDeleteEvent`   | No          | Fired after the world directory is deleted.                                    |
| `BuildWorldLoadEvent`         | **Yes**     | Fired before a world is loaded into server memory.                             |
| `BuildWorldPostLoadEvent`     | No          | Fired after a world is loaded.                                                 |
| `BuildWorldUnloadEvent`       | **Yes**     | Fired before a world is unloaded from server memory.                           |
| `BuildWorldPostUnloadEvent`   | No          | Fired after a world is unloaded.                                               |
| `BuildWorldUnimportEvent`     | No          | Fired when a world is removed from the plugin registry.                        |
| `BuildWorldRenameEvent`       | No          | Fired when a world is renamed.                                                 |
| `BuildWorldStatusChangeEvent` | No          | Fired when a world's build status is modified.                                 |
| `BuildWorldManipulationEvent` | **Yes**     | Core event fired when block placements, breaks, or interactions are processed. |
| `PlayerBuildModeToggleEvent`  | **Yes**     | Fired when a player toggles Build Mode (`/build`) on or off.                   |

### 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.

| Event Class          | Cancellable | Description                                |
| -------------------- | ----------- | ------------------------------------------ |
| `FolderCreatedEvent` | No          | Fired after a new world folder is created. |
| `FolderDeletedEvent` | No          | Fired after a folder is deleted.           |

***

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

Track archiving, uploads, and restorations.

| 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.                |
| `BackupRestoredEvent` | No          | Fired after a backup is restored to a world.                 |