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

# Getting Started

Integrate the **BuildSystem Developer API** (`buildsystem-api` version `4.0.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.0.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.0.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]
  ```