6. API

TimoCloud contains a powerful API. You can use it everywhere - on BungeeCord/Velocity and Bukkit/Spigot.

To add the API as a dependency to your plugin via Maven, add the following to your pom.xml:

<dependencies>
  <dependency>
    <groupId>cloud.timo.timocloud</groupId>
    <artifactId>TimoCloud-API</artifactId>
    <version>6.7.4</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

Visit Maven

Actually, there are 5 API classes:

TimoCloudUniversalAPI

This is the main API. You can access it from your BungeeCord-, Velocity- and Bukkit/Spigot-plugins. Through it, you can get all servers, proxies and players.

Example usages:

List<ServerGroupObject> allServerGroups = TimoCloudAPI.getUniversalAPI().getServerGroups();

ServerGroupObject lobbyGroup = TimoCloudAPI.getUniversalAPI().getGroup("Lobby");

TimoCloudBukkitAPI

This API is only accessible from your Bukkit/Spigot plugins. By now, it only contains one method: getThisServer() - which allows you to get the server you are on as a ServerObject.

Example usages:

ServerObject thisServer = TimoCloudAPI.getBukkitAPI().getThisServer();

thisServer.setState("INGAME");

TimoCloudBungeeAPI / TimoCloudProxyAPI

This API is only accessible from your Proxy plugins. By now, it only contains one method: getThisProxy() - which allows you to get the proxy you are on as a ProxyObject.

Example usages:

ProxyObject thisProxy = TimoCloudAPI.getProxyAPI().getThisProxy();

ProxyGroupObject thisProxyGroup = thisProxy.getGroup();

TimoCloudEventAPI

This API allows you to register Event Listeners which will be called when an event is fired. It is very similar to the event API provided by Bukkit/BungeeCord.

An example class:

import cloud.timo.TimoCloud.api.*;

public class TimoCloudEventListener implements Listener {
    @EventHandler
    public void onPlayerConnectEvent(PlayerConnectEvent event) {
        // Your code
    }

    @EventHandler
    public void onPlayerDisconnectEvent(PlayerDisconnectEvent event) {
        // Your code
    }
}

TimoCloudAPI.getEventAPI().registerListener(new TimoCloudEventListener());

Make sure to use the right imports for Listener, EventHandler and the events. (Don't use the ones starting with org.bukkit... but the ones starting with cloud.timo...)

TimoCloudMessageAPI

This api provides methods to communicate within a TimoCloud network. For example, you can send a message from the server BedWars-1 to the proxy Proxy-2 or from a plugin in the Core to SkyWars-3. Every application in the TimoCloud network (e.g. Core, cords, servers, proxies) is part of the messaging network.

PluginMessage and AddressedPluginMessage

The message API provides methods to send PluginMessage objects. A PluginMessage is basically just a data store object which has a type and data. An example to create a PluginMessage of type "TEST" would be:

PluginMessage pluginMessage = new PluginMessage("TEST").set("playerName", "TimoCrafter").set("balance", 1000.0);

// The message recipient will get this object and can retrieve the properties like this:

String playerName = pluginMessage.getString("playerName"); // "TimoCrafter"
Double balance = pluginMessage.getDouble("balance"); // 1000.0

How to send a message

Here is an example of how to send a message:

TimoCloudAPI.getMessageAPI().sendMessageToServer(pluginMessage, "BedWars-1");

This will send the pluginMessage object to the server "BedWars-1". Similar to sendMessageToServer(PluginMessage message, String serverName), there are the methods sendMessageToProxy(PluginMessage message, String proxyName), sendMessageToCord(PluginMessage message, String cordName) and sendMessageToCore(PluginMessage message).

How to receive messages

In order to receive messages, you just need to register a class implementing MessageListener. The method onPluginMessage(AddressedPluginMessage message) will be called every time a message is sent to you. As every message has a type (a string like "TEST"), you can specify a list of message types when you register a listener. It will only be notified if the received message's type is included in the listeners's list of supported types. If you don’t specify any message types, the listener will listen for all types. Example:

public class PluginMessageListener implements MessageListener {

    @Override
    public void onPluginMessage(AddressedPluginMessage addressedPluginMessage) {
        PluginMessage message = addressedPluginMessage.getMessage();
    }

}

// This listener will be notified of messages of types „TEST“, „PLAYER_JOIN“ and „PLAYER_QUIT“
TimoCloudAPI.getMessageAPI().registerListener(new PluginMessageListener(), „TEST“, „PLAYER_JOIN“, „PLAYER_QUIT“);

// This listener will be notified of messages of all types
TimoCloudAPI.getMessageAPI().registerListener(new PluginMessageListener());