Installation

Dependencies hinzufügen

Füge die Cloud API zu deiner Build-Konfiguration hinzu. Die Beispiele unten laden die neueste verfügbare API-Version aus dem SimpleCloud Maven-Repository.

Verwende compileOnly oder Maven provided für Minecraft-Plugins, weil das simplecloud-api Plugin die API zur Laufzeit bereitstellt. Nutze implementation nur für Standalone-Anwendungen, die die API selbst mitliefern.

Für reproduzierbare Produktionsbuilds solltest du die angezeigte Version nach dem Testen fest pinnen. Aktualisiere diese Seite vor dem Kopieren, wenn du die neueste API verwenden möchtest.

Plugin-Setup

Füge das SimpleCloud API Plugin als Dependency in deinem Plugin-Deskriptor hinzu:

Paper/Spigot (plugin.yml)
Velocity (velocity-plugin.json)
BungeeCord (bungee.yml)

name: mein-plugin
version: 1.0.0
main: com.example.MeinPlugin
depend: [simplecloud-api]

{
  "id": "mein-plugin",
  "name": "Mein Plugin",
  "version": "1.0.0",
  "main": "com.example.MeinPlugin",
  "dependencies": [{ "id": "simplecloud-api", "optional": false }]
}

name: mein-plugin
version: 1.0.0
main: com.example.MeinPlugin
depends: [simplecloud-api]

Shade die Cloud API nicht in dein Plugin. Hänge stattdessen vom simplecloud-api Plugin ab.

API initialisieren

Standard-Konfiguration

Wenn du innerhalb eines SimpleCloud-Servers läufst, konfiguriert sich die API automatisch aus Umgebungsvariablen:

Java
Kotlin

import app.simplecloud.api.CloudApi;

public class MeinPlugin extends JavaPlugin {
    private CloudApi api;

    @Override
    public void onEnable() {
        api = CloudApi.create();
    }
}

import app.simplecloud.api.CloudApi

class MeinPlugin : JavaPlugin() {
    private lateinit var api: CloudApi

    override fun onEnable() {
        api = CloudApi.create()
    }
}

Eigene Konfiguration

Für Standalone-Anwendungen oder eigene Setups, gib Konfigurationsoptionen an:

Java
Kotlin

CloudApi api = CloudApi.create(CloudApiOptions.builder()
    .networkId("deine-netzwerk-id")
    .networkSecret("dein-secret")
    .controllerUrl("https://controller.simplecloud.app")
    .natsUrl("wss://nats.simplecloud.app:443")
    .component("mein-plugin")
    .build());

val api = CloudApi.create(CloudApiOptions.builder()
    .networkId("deine-netzwerk-id")
    .networkSecret("dein-secret")
    .controllerUrl("https://controller.simplecloud.app")
    .natsUrl("wss://nats.simplecloud.app:443")
    .component("mein-plugin")
    .build())

Umgebungsvariablen

Die API liest standardmäßig diese Umgebungsvariablen:

Variable	Standard	Beschreibung
`SIMPLECLOUD_NETWORK_ID`	`"default"`	Deine Netzwerk-Kennung
`SIMPLECLOUD_NETWORK_SECRET`	`""`	Authentifizierungs-Secret
`SIMPLECLOUD_CONTROLLER_URL`	`"https://controller.simplecloud.app"`	Controller API-Endpunkt
`SIMPLECLOUD_NATS_URL`	`"wss://nats.simplecloud.app:443"`	NATS-Endpunkt für Events
`SIMPLECLOUD_NATS_FAILOVER_RECONNECT_AFTER`	`"30s"`	Wartezeit, bevor die API nach einem Failover wieder zu NATS verbindet
`SIMPLECLOUD_SERVER_VERSION_MANIFEST_URL`	SimpleCloud-Server-Manifest auf GitHub	Manifest für Inline-Blueprints ohne `serverUrl`

Innerhalb von SimpleCloud-Servern werden diese Variablen automatisch gesetzt. Du musst sie nur für Standalone-Anwendungen oder externe Services konfigurieren.

Cache und Timeouts

Die API nutzt standardmäßig einen lokalen Query-Cache. Sie liefert frische Cache-Daten sofort, kann veraltete Daten während einer Hintergrund-Aktualisierung zurückgeben und invalidiert betroffene Einträge automatisch, wenn Cloud-API-Events eintreffen.

CloudApi api = CloudApi.create(CloudApiOptions.builder()
    .cache(CacheConfig.builder()
        .defaultStaleTime(Duration.ofSeconds(5))
        .defaultCacheTime(Duration.ofMinutes(2))
        .build())
    .httpConnectTimeout(Duration.ofSeconds(5))
    .httpReadTimeout(Duration.ofSeconds(10))
    .httpWriteTimeout(Duration.ofSeconds(10))
    .build());

// Cache vollständig deaktivieren
CloudApi uncached = CloudApi.create(CloudApiOptions.builder()
    .disableCache()
    .build());

Verwende api.cache(), um Cache-Statistiken zu prüfen oder Einträge manuell zu invalidieren.

Best Practices

Eine einzelne API-Instanz verwenden

Erstelle eine CloudApi-Instanz und verwende sie wieder. Nutze Dependency Injection wenn dein Framework es unterstützt.

// Gut - einzelne Instanz
private final CloudApi api = CloudApi.create();

// Vermeiden - mehrere Instanzen
public void doSomething() {
    CloudApi api = CloudApi.create(); // Das nicht tun
}

Async-Operationen richtig behandeln

Alle API-Methoden geben CompletableFuture zurück. Blockiere nicht auf dem Haupt-Thread.

// Gut - async Behandlung
api.server().getAllServers().thenAccept(servers -> {
    // Server verarbeiten
});

// Vermeiden - blockieren
List<Server> servers = api.server().getAllServers().join(); // Nicht blockieren!

Event-Subscriptions aufräumen

Subscriptions implementieren AutoCloseable. Schließe sie wenn du fertig bist.

Subscription sub = api.event().server().onStarted(event -> {
    System.out.println("Gestartet: " + event.getServer().getServerId());
});

// Beim Herunterfahren
sub.close();

Getting Started

Cloud API

Guides

Dependencies hinzufügen

Plugin-Setup

API initialisieren

Standard-Konfiguration

Eigene Konfiguration

Umgebungsvariablen

Cache und Timeouts

Best Practices

​Dependencies hinzufügen

​Plugin-Setup

​API initialisieren

​Standard-Konfiguration

​Eigene Konfiguration

​Umgebungsvariablen

​Cache und Timeouts

​Best Practices

Dependencies hinzufügen

Plugin-Setup

API initialisieren

Standard-Konfiguration

Eigene Konfiguration

Umgebungsvariablen

Cache und Timeouts

Best Practices