# Entwickler (API)

GWorld v2 bietet eine moderne API, um Welten zu verwalten, zu erstellen und Einstellungen (Flags) programmatisch zu ändern.

**Version v2.0.1**

# 1. Setup & Integration

Um GWorld v2 in deinem Plugin zu nutzen, musst du es als Abhängigkeit (Dependency) hinzufügen.

## 1. Maven Dependency

Füge das `<span class="hljs-code">core</span>`-Modul von GWorld in deine `<span class="hljs-code">pom.xml</span>` ein. Da die API zur Laufzeit vom Server bereitgestellt wird, nutzen wir den Scope `<span class="hljs-code">provided</span>`.

```XML
<dependency>
  <groupId>de.gilljan</groupId>
  <artifactId>gworld-core</artifactId>
  <version>2.0.1-SNAPSHOT</version>
  <scope>provided</scope>
</dependency>
```

Wir verwenden die GitHub Maven Package Registry. Um diese zu verwenden, beachte bitte die Dokumentation von GitHub:   
[https://docs.github.com/de/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry#installing-a-package](https://docs.github.com/de/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry#installing-a-package)

## 2. plugin.yml

Damit dein Plugin sicher auf GWorld zugreifen kann, muss es *nach* GWorld geladen werden. Füge dazu den Eintrag in deine `plugin.yml` hinzu:

```YAML
depend: [GWorld]
# Alternativ, wenn GWorld optional ist:
# softdepend: [GWorld]
```

## 3. Zugriff auf die API

Der Haupteinstiegspunkt ist das Interface `GWorldAPI`. Du erhältst die Instanz über die statische Methode der Hauptklasse.

```JAVA
import de.gilljan.gworld.GWorld;
import de.gilljan.gworld.api.GWorldAPI;
import de.gilljan.gworld.api.IWorldManager;

public class MyPlugin extends JavaPlugin {
    
    private IWorldManager worldManager;

    @Override
    public void onEnable() {
        if (Bukkit.getPluginManager().isPluginEnabled("GWorld")) {
            // API Instanz abrufen
            GWorldAPI api = GWorld.getInstance();
            
            // Den Manager für Welten laden
            this.worldManager = api.getWorldManager();
        }
    }
}
```

# 2. Welten erstellen (Builder)

<span style="white-space: pre-wrap;">In GWorld v2 werden neue Welten über das </span>**Builder-Pattern**<span style="white-space: pre-wrap;"> erstellt. Dies trennt die </span>**Konfiguration**<span style="white-space: pre-wrap;"> (Registrierung) von der </span>**Generierung**<span style="white-space: pre-wrap;"> (Last).</span>

# Schritt 1: Der Builder (Registrierung)

<span style="white-space: pre-wrap;">Mit dem </span>`<span class="editor-theme-code">WorldCreationBuilder</span>`<span style="white-space: pre-wrap;"> legst du alle Eigenschaften der Welt fest. Der Aufruf von </span>`<span class="editor-theme-code">.build()</span>`<span style="white-space: pre-wrap;"> registriert die Welt in der Datenbank, erstellt sie aber noch nicht physikalisch.</span>

```java
import de.gilljan.gworld.api.IManageableWorld;
import de.gilljan.gworld.enums.WorldTypeMapping;

// Startet den Builder
IManageableWorld newWorld = worldManager.createBuilder("MeineEventWelt")
    .worldType(WorldTypeMapping.NORMAL) // Umgebung: Normal, Nether, End, Large Biomes, Amplified, Flat
    .generator("PlotSquared")           // Optional: Custom Generator Name
    .seed(987654321L)                   // Optional: Seed festlegen
    .build();                           // -> Speichert die Welt in die Config/DB
```

<p class="callout info">**Hinweis:**<span style="white-space: pre-wrap;"> Die Methode </span>`<span class="editor-theme-code">.build()</span>`<span style="white-space: pre-wrap;"> ruft intern </span>`<span class="editor-theme-code">addWorldFromBuilder</span>`<span style="white-space: pre-wrap;"> auf. Die Welt ist danach bekannt (</span>`<span class="editor-theme-code">registered</span>`<span style="white-space: pre-wrap;">), aber noch </span>`<span class="editor-theme-code">unloaded</span>`.</p>

## Schritt 2: Laden (Generierung)

```java
// Erstellt die Bukkit-Welt und lädt Chunks
boolean success = newWorld.createMap(); 

if (success) {
  getLogger().info("Welt ist bereit!");
}

```

<p class="callout success"><span style="white-space: pre-wrap;">Für einen Import gilt dies analog. Den Ordnernamen der Welt verwenden und anstatt </span>`<span class="editor-theme-code">createMap()</span>`<span style="white-space: pre-wrap;"> die Methode </span>`<span class="editor-theme-code">importMap()</span>`<span style="white-space: pre-wrap;"> verwenden.</span></p>

## Warum zwei Schritte?

1. **Performance:**<span style="white-space: pre-wrap;"> Du kannst Welten beim Serverstart registrieren, aber erst laden, wenn ein Spieler ein Minigame startet.</span>
2. **Sicherheit:**<span style="white-space: pre-wrap;"> Du kannst Flags (z. B. PvP aus) setzen, bevor der erste Spieler die Welt betritt.</span>

# 3. Management & Steuerung

<span style="white-space: pre-wrap;">Der </span>`<span class="editor-theme-code">IWorldManager</span>`<span style="white-space: pre-wrap;"> verwaltet alle Welten, während das </span>`<span class="editor-theme-code">IManageableWorld</span>`-Objekt die Kontrolle über eine spezifische Welt ermöglicht.

# Welten abrufen

```java
// Einzelne Welt holen
Optional<IManageableWorld> worldOpt = worldManager.getWorld("Lobby");

// Alle Welten auflisten
List<IManageableWorld> allWorlds = worldManager.getWorlds();
```

## Welt-Aktionen

<span style="white-space: pre-wrap;">Jedes </span>`<span class="editor-theme-code">IManageableWorld</span>`-Objekt bietet Methoden zur Steuerung:

<table id="bkmrk-methodebeschreibungl" style="margin-bottom: 32px;"><colgroup><col></col><col></col></colgroup><tbody><tr><td style="border: 1px solid;">**Methode**

</td><td style="border: 1px solid;">**Beschreibung**

</td></tr><tr><td style="border: 1px solid;"><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;loadMap&#40;&#41;&#60;&#47;span&#62;</code>

</td><td style="border: 1px solid;">Lädt die Welt von der Festplatte (Bukkit World Init).

</td></tr><tr><td style="border: 1px solid;"><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;unloadMap&#40;&#41;&#60;&#47;span&#62;</code>

</td><td style="border: 1px solid;">Entlädt die Welt und teleportiert Spieler zum Hauptspawn.

</td></tr><tr><td style="border: 1px solid;"><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;deleteMap&#40;&#41;&#60;&#47;span&#62;</code>

</td><td style="border: 1px solid;">Löscht die Welt unwiderruflich (Dateien &amp; Datenbank-Eintrag).

</td></tr><tr><td style="border: 1px solid;"><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;reCreate&#40;boolean save&#41;&#60;&#47;span&#62;</code>

</td><td style="border: 1px solid;">Löscht die Welt und generiert sie neu (Reset). Optional mit Backup (true) oder ohne (false).

</td></tr><tr><td style="border: 1px solid;"><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;clone&#40;String name&#41;&#60;&#47;span&#62;</code>

</td><td style="border: 1px solid;">Erstellt eine Kopie der Welt unter neuem Namen.

</td></tr></tbody></table>

### Beispiel: Welt-Reset durchführen

```java
worldManager.getWorld("Farmwelt").ifPresent(world -> {
    // Welt zurücksetzen und Kopie der alten Welt behalten
    world.reCreate(true); 
});
```

### Beispiel: Welt entfernen (aus dem System)

Wenn du eine Welt aus GWorld entfernen möchtest (inklusive Löschung der Dateien):

```java
// Variante A: Direkt über das Objekt (Empfohlen)
world.deleteMap();

// Variante B: Über den Manager
worldManager.removeWorld(world);
```

# 4. Flags & Properties

GWorld erlaubt es, Welteinstellungen (Flags) programmatisch zu ändern. Diese Einstellungen werden persistent gespeichert.

# Flags setzen

<span style="white-space: pre-wrap;">Du kannst Flags direkt am </span>`<span class="editor-theme-code">IManageableWorld</span>`-Objekt ändern oder schon während der Erstellung im Builder setzen.

```java
// Beispiel: PvP deaktivieren und Schwierigkeit ändern
world.setAllowPvP(false);
world.setDifficulty(Difficulty.HARD);

// WICHTIG: Speichern, damit es nach Neustart erhalten bleibt!
world.saveProperties();
```

## Verfügbare Einstellungen

<span style="white-space: pre-wrap;">Hier ist eine Übersicht der wichtigsten Methoden im </span>`<span class="editor-theme-code">IManageableWorld</span>`<span style="white-space: pre-wrap;"> Interface:</span>

<table id="bkmrk-kategoriemethoden-%28g" style="margin-bottom: 32px;"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><td style="border: 1px solid;">**Kategorie**

</td><td style="border: 1px solid;">**Methoden (Getter / Setter)**

</td><td style="border: 1px solid;">**Beschreibung**

</td></tr><tr><td style="border: 1px solid;">**Kampf**

</td><td style="border: 1px solid;"><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;isAllowPvP&#60;&#47;span&#62;</code><span style="white-space: pre-wrap;">, </span><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;setAllowPvP&#60;&#47;span&#62;</code>

</td><td style="border: 1px solid;">Globales PvP an/aus.

</td></tr><tr><td style="border: 1px solid;">**Spawning**

</td><td style="border: 1px solid;"><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;isMonsterSpawning&#60;&#47;span&#62;</code><span style="white-space: pre-wrap;">, </span><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;setMonsterSpawning&#60;&#47;span&#62;</code>

</td><td style="border: 1px solid;">Spawnen von Monstern.

</td></tr><tr><td style="border: 1px solid;"></td><td style="border: 1px solid;"><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;isAnimalSpawning&#60;&#47;span&#62;</code><span style="white-space: pre-wrap;">, </span><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;setAnimalSpawning&#60;&#47;span&#62;</code>

</td><td style="border: 1px solid;">Spawnen von Tieren.

</td></tr><tr><td style="border: 1px solid;">**Umgebung**

</td><td style="border: 1px solid;"><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;isWeatherCycle&#60;&#47;span&#62;</code><span style="white-space: pre-wrap;">, </span><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;setWeatherCycle&#60;&#47;span&#62;</code>

</td><td style="border: 1px solid;">Ob sich das Wetter ändert.

</td></tr><tr><td style="border: 1px solid;"></td><td style="border: 1px solid;"><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;isTimeCycle&#60;&#47;span&#62;</code><span style="white-space: pre-wrap;">, </span><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;setTimeCycle&#60;&#47;span&#62;</code>

</td><td style="border: 1px solid;">Ob die Tageszeit voranschreitet.

</td></tr><tr><td style="border: 1px solid;"></td><td style="border: 1px solid;"><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;getTime&#60;&#47;span&#62;</code><span style="white-space: pre-wrap;">, </span><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;setTime&#60;&#47;span&#62;</code>

</td><td style="border: 1px solid;">Aktuelle Zeit in Ticks.

</td></tr><tr><td style="border: 1px solid;">**Spieler**

</td><td style="border: 1px solid;"><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;getGameMode&#60;&#47;span&#62;</code><span style="white-space: pre-wrap;">, </span><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;setGameMode&#60;&#47;span&#62;</code>

</td><td style="border: 1px solid;">Standard-Spielmodus der Welt.

</td></tr><tr><td style="border: 1px solid;">**System**

</td><td style="border: 1px solid;"><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;isLoadOnStartup&#60;&#47;span&#62;</code><span style="white-space: pre-wrap;">, </span><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;setLoadOnStartup&#60;&#47;span&#62;</code>

</td><td style="border: 1px solid;">Soll die Welt beim Serverstart geladen werden?

</td></tr><tr><td style="border: 1px solid;"></td><td style="border: 1px solid;"><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;isKeepSpawnInMemory&#60;&#47;span&#62;</code><span style="white-space: pre-wrap;">, </span><code>&#60;span class&#61;&#34;editor&#45;theme&#45;code&#34;&#62;setKeepSpawnInMemory&#60;&#47;span&#62;</code>

</td><td style="border: 1px solid;">Spawn-Chunks im RAM behalten.

</td></tr></tbody></table>

## Nutzung im Builder

<span style="white-space: pre-wrap;">Wenn du eine Welt erstellst, kannst du Flags auch generisch über </span>`<span class="editor-theme-code">WorldProperty</span>`<span style="white-space: pre-wrap;"> setzen:</span>

```java
import de.gilljan.gworld.data.properties.WorldProperty;

manager.createBuilder("Lobby")
    .property(WorldProperty.PVP, false)
    .property(WorldProperty.ANIMALS, false) 
    .build();
```