> 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/getting-started.md).

# Getting Started

Add the dependency and get hold of the API.

Integrate the **BuildSystem Developer API** (`buildsystem-api` version `4.1.0`) to interface with world services, player configurations, and backup operations.

***

## 1. Adding BuildSystem to your Project

### Maven

Add the dependency inside your `pom.xml`:

```xml
<dependency>
    <groupId>de.eintosti</groupId>
    <artifactId>buildsystem-api</artifactId>
    <version>4.1.0</version>
    <scope>provided</scope>
</dependency>
```

### Gradle (Kotlin DSL)

Add the dependency inside your `build.gradle.kts`:

```kotlin
repositories {
    mavenCentral()
}

dependencies {
    compileOnly("de.eintosti:buildsystem-api:4.1.0")
}
```

{% hint style="info" %}
The api is compiled against **Java 25**. Your development environment and target server runtime must be Java 25 or higher.
{% endhint %}

***

## 2. Obtaining the API Instance

BuildSystem registers its API instance through Bukkit's standard `ServicesManager` during its `onEnable` phase.

### Method A: Static Accessor Shorthand

Use the convenience provider class to fetch the active singleton:

```java
import de.eintosti.buildsystem.api.BuildSystem;
import de.eintosti.buildsystem.api.BuildSystemProvider;

try {
    BuildSystem api = BuildSystemProvider.get();
    // Your integration logic
} catch (IllegalStateException e) {
    // BuildSystem has not finished enabling or has already disabled
}
```

### Method B: Bukkit `ServicesManager`

Resolve the provider manually through Spigot's standard service framework:

```java
import de.eintosti.buildsystem.api.BuildSystem;
import org.bukkit.Bukkit;
import org.bukkit.plugin.RegisteredServiceProvider;

RegisteredServiceProvider<BuildSystem> provider = 
    Bukkit.getServicesManager().getRegistration(BuildSystem.class);

if (provider != null) {
    BuildSystem api = provider.getProvider();
    // Your integration logic
}
```

***

## 3. Lifecycle & Timing Rules

* **Availability**: The instance is registered during the BuildSystem plugin's `onEnable` and unregistered during its `onDisable`.
* **Execution Constraint**: Resolving the service before BuildSystem enables (e.g., inside your plugin's `onLoad()` method) will throw an `IllegalStateException`. Always access the API inside or after your own plugin's `onEnable()` method.
* **Plugin Dependency**: Ensure your `plugin.yml` or `paper-plugin.yml` declares BuildSystem as a dependency to enforce correct loading orders:

  ```yaml
  # plugin.yml
  depend: [BuildSystem]
  ```

***

## 4. What the API Exposes

`BuildSystem` is the root of the API. Everything else hangs off its getters:

| Getter                           | Returns                     | Used for                                                                                                                                                                                              |
| -------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getWorldService()`              | `WorldService`              | Creating, importing, unimporting and deleting worlds, and the `WorldStorage` / `FolderStorage` lookups. See [World Management](https://buildsystem.eintosti.de/developer-portal/world-management.md). |
| `getPlayerService()`             | `PlayerService`             | Per-player settings (`getPlayerStorage().getBuildPlayer(player).getSettings()`), build mode, and world creation limits (`canCreateWorld`, `getMaxWorlds`).                                            |
| `getBackupService()`             | `BackupService`             | Listing, creating and restoring backups. See [Backup Service](https://buildsystem.eintosti.de/developer-portal/backup-service.md).                                                                    |
| `getStatusRegistry()`            | `WorldStatusRegistry`       | The built-in and custom world statuses.                                                                                                                                                               |
| `getNavigatorCategoryRegistry()` | `NavigatorCategoryRegistry` | The built-in and custom navigator categories.                                                                                                                                                         |

{% hint style="info" %}
`PlayerService#enterBuildMode(UUID)` and `leaveBuildMode(UUID)` only add the player to, or remove them from, the build-mode set. They do not fire `PlayerBuildModeToggleEvent` and do not save or restore the player's state the way `/build` does.
{% endhint %}
