Installation

Add the API dependency

The Cloud API requires Java 21. Add the SimpleCloud and Buf repositories, then add the API with compileOnly in Gradle or provided in Maven:

Do not shade the Cloud API into your plugin. The simplecloud-api platform plugin provides it at runtime, and bundling another copy can cause class-loading conflicts.

Pin the dependency to the version you tested before releasing your plugin.

Require the platform plugin

Declare simplecloud-api as a required dependency so it loads before your plugin. SimpleCloud’s default templates already include the matching platform plugin. If you use custom templates, keep it in the plugins directory.

Paper
Folia
Spigot
Velocity
BungeeCord

Add the dependency to src/main/resources/paper-plugin.yml:

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

Add the dependency to src/main/resources/plugin.yml:

plugin.yml

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

Add the dependency to src/main/resources/plugin.yml:

plugin.yml

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

Add the dependency to the @Plugin annotation on your main class:

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 {
}

Add the dependency to src/main/resources/plugin.yml:

plugin.yml

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

Create one client

Create a CloudApi instance when your plugin starts, reuse it for every request, and close it when your plugin stops. SimpleCloud provides the connection settings automatically.

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();
        }
    }
}

Most API calls return CompletableFuture; compose them instead of blocking, and use your platform’s scheduler before changing platform state from a callback.

Velocity lifecycle

On Velocity, create and close the same client from the proxy lifecycle events:

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() uses the connection settings supplied by SimpleCloud. If your plugin needs different request timeouts or cache behavior, pass a custom CloudApiOptions instance.

Troubleshooting

The API dependency cannot be resolved

Confirm that your build contains both repositories shown above, then refresh dependencies with ./gradlew --refresh-dependencies or mvn -U package.

The plugin fails with NoClassDefFoundError

Check that:

The matching simplecloud-api platform plugin is installed and enabled.
Your plugin declares it as a required dependency. Paper plugins also need join-classpath: true.
Your build uses compileOnly or provided and does not shade the API.

CloudApi.create() fails

Confirm that SimpleCloud started the server and that the matching simplecloud-api platform plugin is enabled.

Getting Started

Cloud API

Guides

REST API Reference

Add the API dependency

Require the platform plugin

Create one client

Velocity lifecycle

Troubleshooting

​Add the API dependency

​Require the platform plugin

​Create one client

​Velocity lifecycle

​Troubleshooting

Add the API dependency

Require the platform plugin

Create one client

Velocity lifecycle

Troubleshooting