📡API

API Setup

To use the API, you should begin by compiling it. Follow these steps:

• Clone the repository with git clone https://github.com/Smooth-Plugins/SmoothSyncAPI.git.

• Compile it with Maven using mvn clean install.

Setup with Maven

To integrate the API using Maven, add the following code to your pom.xml file:

<dependencies>
    <dependency>
        <groupId>net.smoothplugins</groupId>
        <artifactId>SmoothSyncAPI</artifactId>
        <version>%POM-VERSION%</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Setup with Gradle

If you're using Gradle, add the following code to your build.gradle file:

dependencies {
    compileOnly 'net.smoothplugins:SmoothSyncAPI:%POM-VERSION%'
}

Replace %POM-VERSION% with the appropriate version of the API.

Final step

To complete the setup, include SmoothSync as a dependency (or softdepend) in your plugin.yml:

name: MyPlugin
version: 1.0
main: net.smoothplugins.myplugin.MyPlugin
author: Author
depend:
  - SmoothSync

Getting the API

Now, you can get the SmoothSyncAPI to interact with SmoothSync within your plugin's code:

@Override
public void onEnable() {
    SmoothSyncAPI smoothSyncAPI = getSmoothSyncAPI();
}

private SmoothSyncAPI getSmoothSyncAPI() {
    if (Bukkit.getPluginManager().getPlugin("SmoothSync") != null) {
        RegisteredServiceProvider<SmoothSyncAPI> rsp = Bukkit.getServicesManager().getRegistration(SmoothSyncAPI.class);
        return rsp.getProvider();
    }

    return null;
}

Interact with the API

It is recommended to interact asynchronously with all methods of the API, except for the UserTranslator#translateToPlayer method.

Get a User by their UUID or username

To retrieve a User based on a player's UUID or username, follow this example:

import net.smoothplugins.smoothsyncapi.SmoothSyncAPI;
import net.smoothplugins.smoothsyncapi.user.User;

import java.util.Optional;
import java.util.UUID;

public class Example {

    private final SmoothSyncAPI smoothSyncAPI;

    public Example(SmoothSyncAPI smoothSyncAPI) {
        this.smoothSyncAPI = smoothSyncAPI;
    }

    public Optional<User> getUserByUUID(UUID uuid) {
        return smoothSyncAPI.getUserService().getUserByUUID(uuid);
    }

    public Optional<User> getUserByUsername(String username) {
        return smoothSyncAPI.getUserService().getUserByUsername(username);
    }
}

Update a User

To update a User, you will need to provide the User object and the destination(s), as shown in this example:

import net.smoothplugins.smoothsyncapi.SmoothSyncAPI;
import net.smoothplugins.smoothsyncapi.service.Destination;
import net.smoothplugins.smoothsyncapi.user.User;

public class Example {

    private final SmoothSyncAPI smoothSyncAPI;

    public Example(SmoothSyncAPI smoothSyncAPI) {
        this.smoothSyncAPI = smoothSyncAPI;
    }

    public void updateUser(User user, Destination... destinations) {
        smoothSyncAPI.getUserService().update(user, destinations);
    }
}

When specifying destinations, you can indicate where you wish to update the User. The available destinations are:

• STORAGE

• CACHE

• CACHE_IF_PRESENT

• PLAYER_IF_ONLINE

If you choose PLAYER_IF_ONLINE, SmoothSync will initiate a broadcast message, and all servers will verify if the player is currently connected. If any server has the player online, the data will be translated to the User.

Translate between a User and a Player

SmoothSync enables the translation between a User and a Player using the UserTranslator:

import net.smoothplugins.smoothsyncapi.SmoothSyncAPI;
import net.smoothplugins.smoothsyncapi.user.User;
import org.bukkit.entity.Player;

public class Example {

    private final SmoothSyncAPI smoothSyncAPI;

    public Example(SmoothSyncAPI smoothSyncAPI) {
        this.smoothSyncAPI = smoothSyncAPI;
    }

    public void translateToPlayer(User user, Player base) {
        smoothSyncAPI.getUserTranslator().translateToPlayer(user, base);
    }
    
    public void translateToUser(User base, Player player) {
        smoothSyncAPI.getUserTranslator().translateToUser(base, player);
    }
}

Get a current version of a User

If you use this method to obtain a User and the Player is currently connected, it might not reflect the most up-to-date version of the Player. To address this, SmoothSync provides a method to retrieve the present version of a connected player:

import net.smoothplugins.smoothsyncapi.SmoothSyncAPI;
import net.smoothplugins.smoothsyncapi.user.User;

import java.util.Optional;
import java.util.UUID;

public class Example {

    private final SmoothSyncAPI smoothSyncAPI;

    public Example(SmoothSyncAPI smoothSyncAPI) {
        this.smoothSyncAPI = smoothSyncAPI;
    }

    public Optional<User> getUpdatedUserByUUID(UUID uuid) {
        try {
            return smoothSyncAPI.getUserService().requestUpdatedUserByUUID(uuid);
        } catch (InterruptedException ignored) {
            return Optional.empty();
        }
    }
    
    public Optional<User> getUpdatedUserByUsername(String username) {
        try {
            return smoothSyncAPI.getUserService().requestUpdatedUserByUsername(username);
        } catch (InterruptedException ignored) {
            return Optional.empty();
        }
    }
}

This method is more resource-intensive compared to the regular get method. Therefore, you should only employ this method in specific situations that necessitate the most current version of the user (such as when using the /invsee command).

Manage custom extra data

SmoothSync has been designed to allow other developers to seamlessly integrate custom data into the User object. Managing this functionality is straightforward:

import net.smoothplugins.smoothsyncapi.SmoothSyncAPI;
import net.smoothplugins.smoothsyncapi.service.Destination;
import net.smoothplugins.smoothsyncapi.user.User;

import java.util.UUID;

public class Example {

    private final SmoothSyncAPI smoothSyncAPI;

    public Example(SmoothSyncAPI smoothSyncAPI) {
        this.smoothSyncAPI = smoothSyncAPI;
    }

    public void example(UUID uuid) {
        User user = smoothSyncAPI.getUserService().getUserByUUID(uuid).orElse(null);
        if (user == null) return;

        double exampleCoins = (double) user.getExtraData().getOrDefault("example_coins", 0d);

        if (exampleCoins < 100) {
            user.getExtraData().put("example_coins", 100);
            smoothSyncAPI.getUserService().update(user, Destination.STORAGE, Destination.CACHE_IF_PRESENT);
        }
    }
}

Events

You can listen to events in the same way as a typical Bukkit event.

Class	Cancellable	Description
DataCleanEvent	Yes	When a user joins the server, his data is cleared (inventory, enderchest and experience) to avoid conflicts and duplication of items. This event is called before the data is cleared.
DataSyncEvent	Yes	This event is called before the data is synchronized.
AsyncDataUpdateEvent	Yes	This event is called before the data is saved.