> ## Documentation Index
> Fetch the complete documentation index at: https://new-docs.simplecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Cloud API zu deinem Minecraft-Plugin oder Standalone-Anwendung hinzufügen

export const DependencySnippet = ({dependencies = [], repositories = [{
  id: "simplecloud",
  url: "https://repo.simplecloud.app/snapshots"
}, {
  id: "buf",
  url: "https://buf.build/gen/maven"
}], type = "snapshot"}) => {
  const [versions, setVersions] = useState({});
  useEffect(() => {
    dependencies.forEach(dep => {
      if (dep.version) return;
      const fetchVersion = async () => {
        try {
          const url = type === "snapshot" ? `https://repo.simplecloud.app/api/maven/latest/version/snapshots/${dep.groupId.replace(/\./g, "/")}/${dep.artifactId}?type=raw` : `https://search.maven.org/solrsearch/select?q=g:${dep.groupId}+AND+a:${dep.artifactId}&rows=1&wt=json`;
          const res = await fetch(url);
          if (type === "snapshot") {
            const version = await res.text();
            setVersions(prev => ({
              ...prev,
              [`${dep.groupId}:${dep.artifactId}`]: version.trim()
            }));
          } else {
            const data = await res.json();
            const version = data.response?.docs?.[0]?.latestVersion;
            if (version) {
              setVersions(prev => ({
                ...prev,
                [`${dep.groupId}:${dep.artifactId}`]: version
              }));
            }
          }
        } catch (e) {
          console.error("Failed to fetch version", e);
        }
      };
      fetchVersion();
    });
  }, [dependencies, type]);
  const getVersion = dep => {
    if (dep.version) return dep.version;
    return versions[`${dep.groupId}:${dep.artifactId}`] || "LATEST";
  };
  const generateKotlin = () => {
    const repoLines = repositories.map(r => `    maven("${r.url}")`).join("\n");
    const depLines = dependencies.map(dep => {
      const depType = dep.type || "implementation";
      return `    ${depType}("${dep.groupId}:${dep.artifactId}:${getVersion(dep)}")`;
    }).join("\n");
    return `repositories {\n${repoLines}\n}\n\ndependencies {\n${depLines}\n}`;
  };
  const generateGroovy = () => {
    const repoLines = repositories.map(r => `    maven { url '${r.url}' }`).join("\n");
    const depLines = dependencies.map(dep => {
      const depType = dep.type || "implementation";
      return `    ${depType} '${dep.groupId}:${dep.artifactId}:${getVersion(dep)}'`;
    }).join("\n");
    return `repositories {\n${repoLines}\n}\n\ndependencies {\n${depLines}\n}`;
  };
  const generateMaven = () => {
    const repoLines = repositories.map(r => `    <repository>
      <id>${r.id || 'repo'}</id>
      <url>${r.url}</url>
    </repository>`).join("\n");
    const depLines = dependencies.map(dep => {
      const scope = dep.type === "compileOnly" ? "provided" : "compile";
      return `    <dependency>
      <groupId>${dep.groupId}</groupId>
      <artifactId>${dep.artifactId}</artifactId>
      <version>${getVersion(dep)}</version>
      <scope>${scope}</scope>
    </dependency>`;
    }).join("\n");
    return `<repositories>\n${repoLines}\n</repositories>\n\n<dependencies>\n${depLines}\n</dependencies>`;
  };
  return <Tabs>
      <Tab title="Gradle (Kotlin)">
        <CodeBlock language="kotlin">
          {generateKotlin()}
        </CodeBlock>
      </Tab>
      <Tab title="Gradle (Groovy)">
        <CodeBlock language="groovy">
          {generateGroovy()}
        </CodeBlock>
      </Tab>
      <Tab title="Maven">
        <CodeBlock language="xml">
          {generateMaven()}
        </CodeBlock>
      </Tab>
    </Tabs>;
};

## Dependencies hinzufügen

Füge die Cloud API zu deiner Build-Konfiguration hinzu. Die Version wird automatisch aus unserem Maven-Repository abgerufen.

<DependencySnippet
  dependencies={[
{
  groupId: "app.simplecloud.api",
  artifactId: "api",
  type: "implementation",
},
]}
  repositories={[
{ id: "simplecloud", url: "https://repo.simplecloud.app/snapshots" },
{ id: "buf", url: "https://buf.build/gen/maven" },
]}
  type="snapshot"
/>

## Plugin-Setup

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

<Tabs>
  <Tab title="Paper/Spigot (plugin.yml)">
    ```yaml theme={null}
    name: mein-plugin
    version: 1.0.0
    main: com.example.MeinPlugin
    depend: [simplecloud-api]
    ```
  </Tab>

  <Tab title="Velocity (velocity-plugin.json)">
    ```json theme={null}
    {
      "id": "mein-plugin",
      "name": "Mein Plugin",
      "version": "1.0.0",
      "main": "com.example.MeinPlugin",
      "dependencies": [{ "id": "simplecloud-api", "optional": false }]
    }
    ```
  </Tab>

  <Tab title="BungeeCord (bungee.yml)">
    ```yaml theme={null}
    name: mein-plugin
    version: 1.0.0
    main: com.example.MeinPlugin
    depends: [simplecloud-api]
    ```
  </Tab>
</Tabs>

<Warning>
  Shade die Cloud API nicht in dein Plugin. Hänge stattdessen vom
  `simplecloud-api` Plugin ab.
</Warning>

## API initialisieren

### Standard-Konfiguration

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

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    import app.simplecloud.api.CloudApi;

    public class MeinPlugin extends JavaPlugin {
        private CloudApi api;

        @Override
        public void onEnable() {
            api = CloudApi.create();
        }
    }
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    import app.simplecloud.api.CloudApi

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

        override fun onEnable() {
            api = CloudApi.create()
        }
    }
    ```
  </Tab>
</Tabs>

### Eigene Konfiguration

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

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    CloudApi api = CloudApi.create(CloudApiOptions.builder()
        .networkId("deine-netzwerk-id")
        .networkSecret("dein-secret")
        .controllerUrl("https://controller.simplecloud.app")
        .natsUrl("nats://platform.simplecloud.app:4222")
        .build());
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val api = CloudApi.create(CloudApiOptions.builder()
        .networkId("deine-netzwerk-id")
        .networkSecret("dein-secret")
        .controllerUrl("https://controller.simplecloud.app")
        .natsUrl("nats://platform.simplecloud.app:4222")
        .build())
    ```
  </Tab>
</Tabs>

## 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`       | `"nats://platform.simplecloud.app:4222"` | NATS-Server für Events    |

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

## Best Practices

<AccordionGroup>
  <Accordion title="Eine einzelne API-Instanz verwenden">
    Erstelle eine `CloudApi`-Instanz und verwende sie wieder. Nutze Dependency Injection wenn dein Framework es unterstützt.

    ```java theme={null}
    // Gut - einzelne Instanz
    private final CloudApi api = CloudApi.create();

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

  <Accordion title="Async-Operationen richtig behandeln">
    Alle API-Methoden geben `CompletableFuture` zurück. Blockiere nicht auf dem Haupt-Thread.

    ```java theme={null}
    // Gut - async Behandlung
    api.server().getAllServers().thenAccept(servers -> {
        // Server verarbeiten
    });

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

  <Accordion title="Event-Subscriptions aufräumen">
    Subscriptions implementieren `AutoCloseable`. Schließe sie wenn du fertig bist.

    ```java theme={null}
    Subscription sub = api.event().server().onStarted(event -> { ... });

    // Beim Herunterfahren
    sub.close();
    ```
  </Accordion>
</AccordionGroup>