Developer Reference

The TaktCloud API

Build plugins and integrations against taktOS – manage services, groups, players, permissions and more from your own code, without touching the network protocol.

⚙ WORK IN PROGRESS

The API is still in development

This page is a preview of what the TaktCloud API will offer. The API is not part of the cloud download yet – once it is ready it will be shipped as a separate download (its own taktcloud-api.jar) so you can add it to your plugin projects.

Separate download. The API ships on its own and is versioned independently of the cloud.
Backwards compatible. It is designed to work with all previous cloud versions – it talks to taktOS over the same stable packet protocol that every release already speaks.
Preview code. The class and method names in the examples below are illustrative and may still change before the first release.

iOverview

The TaktCloud API is a small Java library you add to a plugin running on a cloud server (Paper) or on the proxy (Velocity). It gives you a clean, typed entry point to everything taktOS manages – so you never have to build packets or parse JSON yourself.

One entry point. Grab the API with a single call and reach every subsystem through it.
Sync & async. Read cached state instantly, or perform actions that talk to taktOS asynchronously so the main thread never blocks.
Event driven. Listen for cloud events (service start/stop, player switch, maintenance toggles) right where they happen.
Platform-neutral. The same API surface works from a Paper plugin and from a Velocity plugin.

1What the API will cover

These are the areas the API is planned to expose. Each one mirrors a subsystem taktOS already runs today.

2What it offers (functions)

A quick tour of the surface. Everything hangs off the single TaktCloud.api() entry point.

Services – list, start, stop

JAVA

import dev.taktcloud.api.TaktCloud;
import dev.taktcloud.api.service.ServiceInfo;

var api = TaktCloud.api();

// every running Lobby instance
for (ServiceInfo s : api.services().ofGroup("Lobby")) {
    System.out.println(s.getName() + " @ " + s.getHost() + ":" + s.getPort()
        + " – " + s.getOnlinePlayers() + "/" + s.getMaxPlayers());
}

// start two more BedWars instances, stop one lobby
api.services().start("BedWars", 2);
api.services().stop("Lobby-1");

Players – find & move them between servers

JAVA

api.players().find("Notch").ifPresent(p -> p.connect("Lobby"));

// send everyone on a dying server back to the lobby
api.players().on("BedWars-3").forEach(p -> p.connect("Lobby"));

Permissions – check & edit

JAVA

boolean canFly = api.permissions().has(uuid, "taktcloud.fly");

api.permissions().group("vip")
   .add("taktcloud.fly")
   .setPrefix("&6[VIP] &r")
   .save();

Maintenance – proxy or per group

JAVA

api.maintenance().enable();              // whole proxy
api.maintenance().enable("Lobby");       // only the Lobby group
api.maintenance().whitelist().add("Notch");

Events – react to the cloud

JAVA

api.events().on(ServiceStartEvent.class, e ->
    getLogger().info(e.service().getName() + " is now online"));

api.events().on(PlayerSwitchEvent.class, e ->
    getLogger().info(e.player().getName() + " → " + e.to().getName()));

Messaging – your own packets between servers

JAVA

api.messaging().channel("myminigame")
   .onMessage((from, data) -> handle(from, data));

api.messaging().channel("myminigame")
   .send("Lobby-1", "party-invite:Notch");

3How to integrate it

Once the API is released, adding it to a plugin takes three steps. It is a provided dependency – the cloud already ships the runtime, so you only compile against it.

Add the dependency

Drop taktcloud-api.jar from the separate download into your project, or use it from your local Maven repository. Scope it provided so it is not shaded into your plugin.

Maven

XML

<dependency>
  <groupId>dev.taktcloud</groupId>
  <artifactId>taktcloud-api</artifactId>
  <version>1.0.0</version>
  <scope>provided</scope>
</dependency>

Gradle

KOTLIN DSL

compileOnly("dev.taktcloud:taktcloud-api:1.0.0")

Declare the dependency on your plugin

So the cloud loads before your plugin and the API is ready when you ask for it.

Paper – plugin.yml

YAML

name: MyPlugin
main: com.example.MyPlugin
version: 1.0
depend: [TaktCloud]

Velocity – @Plugin

JAVA

@Plugin(id = "myplugin", dependencies = {
    @Dependency(id = "taktcloud")
})

Get the API and go

Grab the singleton in onEnable and keep it. That is it.

Paper

JAVA

public class MyPlugin extends JavaPlugin {
    private TaktCloudAPI cloud;

    @Override
    public void onEnable() {
        cloud = TaktCloud.api();
        getLogger().info("Connected to " + cloud.services().all().size() + " services");
    }
}

4Compatibility

ALL VERSIONS

The API is a thin, stable wrapper over the taktOS packet protocol that every release already speaks. That means it is designed to work with all previous cloud versions – you keep your current taktOS.jar and just add the API to your plugin. The API carries its own version number and evolves without forcing a cloud update.