Installation

API-Abhängigkeit hinzufügen

Die Cloud API benötigt Java 21. Füge die SimpleCloud- und Buf-Repositories hinzu und binde die API mit compileOnly in Gradle oder provided in Maven ein:

Binde die Cloud API nicht per Shading in dein Plugin ein. Das Plattform-Plugin simplecloud-api stellt sie zur Laufzeit bereit. Eine zusätzlich gebündelte Kopie kann zu Konflikten beim Laden von Klassen führen.

Lege die Abhängigkeit vor der Veröffentlichung deines Plugins auf die von dir getestete Version fest.

Plattform-Plugin voraussetzen

Deklariere simplecloud-api als erforderliche Abhängigkeit, damit es vor deinem Plugin geladen wird. Die Standard-Templates von SimpleCloud enthalten bereits das passende Plattform-Plugin. Wenn du eigene Templates verwendest, muss es im Verzeichnis plugins liegen.

Paper
Folia
Spigot
Velocity
BungeeCord

Füge die Abhängigkeit in src/main/resources/paper-plugin.yml hinzu:

paper-plugin.yml

name: my-plugin
version: "1.0.0"
main: com.example.MyPlugin
api-version: "1.21"
dependencies:
  server:
    simplecloud-api:
      load: BEFORE
      required: true
      join-classpath: true

Füge die Abhängigkeit in src/main/resources/plugin.yml hinzu:

plugin.yml

name: my-plugin
version: "1.0.0"
main: com.example.MyPlugin
api-version: "1.21"
folia-supported: true
depend:
  - simplecloud-api

Füge die Abhängigkeit in src/main/resources/plugin.yml hinzu:

plugin.yml

name: my-plugin
version: "1.0.0"
main: com.example.MyPlugin
api-version: "1.20"
depend:
  - simplecloud-api

Füge die Abhängigkeit zur Annotation @Plugin deiner Hauptklasse hinzu:

MyPlugin.java

import com.velocitypowered.api.plugin.Dependency;
import com.velocitypowered.api.plugin.Plugin;

@Plugin(
    id = "my-plugin",
    name = "My Plugin",
    version = "1.0.0",
    dependencies = {@Dependency(id = "simplecloud-api")}
)
public final class MyPlugin {
}

Füge die Abhängigkeit in src/main/resources/plugin.yml hinzu:

plugin.yml

name: my-plugin
version: "1.0.0"
main: com.example.MyPlugin
depends:
  - simplecloud-api

Einen Client erstellen

Erstelle beim Start deines Plugins eine CloudApi-Instanz, verwende sie für alle Anfragen wieder und schließe sie, wenn dein Plugin beendet wird. SimpleCloud stellt die Verbindungseinstellungen automatisch bereit.

MyPlugin.java

package com.example;

import app.simplecloud.api.CloudApi;
import org.bukkit.plugin.java.JavaPlugin;

public final class MyPlugin extends JavaPlugin {
    private CloudApi cloudApi;

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

    @Override
    public void onDisable() {
        if (cloudApi != null) {
            cloudApi.close();
        }
    }
}

Die meisten API-Aufrufe geben ein CompletableFuture zurück. Verknüpfe sie, statt zu blockieren, und wechsle über den Scheduler deiner Plattform zurück in deren Ausführungskontext, bevor du aus einem Callback heraus Plattformzustand änderst.

Velocity-Lebenszyklus

Erstelle und schließe auf Velocity denselben Client über die Lebenszyklus-Events des Proxys:

MyPlugin.java

private CloudApi cloudApi;

@Subscribe
public void onProxyInitialize(ProxyInitializeEvent event) {
    cloudApi = CloudApi.create();
}

@Subscribe
public void onProxyShutdown(ProxyShutdownEvent event) {
    if (cloudApi != null) {
        cloudApi.close();
    }
}

CloudApi.create() verwendet die von SimpleCloud bereitgestellten Verbindungseinstellungen. Wenn dein Plugin andere Zeitlimits für Anfragen oder ein anderes Cache-Verhalten benötigt, übergib eine eigene CloudApiOptions-Instanz.

Fehlerbehebung

Die API-Abhängigkeit kann nicht aufgelöst werden

Prüfe, ob dein Build beide oben gezeigten Repositories enthält. Aktualisiere anschließend die Abhängigkeiten mit ./gradlew --refresh-dependencies oder mvn -U package.

Das Plugin schlägt mit NoClassDefFoundError fehl

Prüfe Folgendes:

Das passende Plattform-Plugin simplecloud-api ist installiert und aktiviert.
Dein Plugin deklariert es als erforderliche Abhängigkeit. Paper-Plugins benötigen außerdem join-classpath: true.
Dein Build verwendet compileOnly oder provided und bindet die API nicht per Shading ein.

CloudApi.create() schlägt fehl

Prüfe, ob SimpleCloud den Server gestartet hat und das passende Plattform-Plugin simplecloud-api aktiviert ist.

Getting Started

Cloud API

Guides

API-Abhängigkeit hinzufügen

Plattform-Plugin voraussetzen

Einen Client erstellen

Velocity-Lebenszyklus

Fehlerbehebung

​API-Abhängigkeit hinzufügen

​Plattform-Plugin voraussetzen

​Einen Client erstellen

​Velocity-Lebenszyklus

​Fehlerbehebung

API-Abhängigkeit hinzufügen

Plattform-Plugin voraussetzen

Einen Client erstellen

Velocity-Lebenszyklus

Fehlerbehebung