Setup
Features
- 🖥️ Commands
- ✅ Sync Features
- ⚙️ Sync Modes
- ↪️ Data Rotation
- ❓ FAQs
Guides
- ↗️ Legacy Migration
- ✨ MPDB Migration
- ☂️ Dumping UserData
- 🟩 Plan Hook
- 📋 Event Priorities
- ⚔️ Keep Inventory
- 🎏 Translations
The HuskSync API (v3) provides methods for retrieving and updating data snapshots, a number of API Events for tracking when user data is synced and saved, and infrastructure for registering serializers to synchronise custom data types.
The HuskSync API shares version numbering with the plugin itself for consistency and convenience. Please note minor and patch plugin releases may make API additions and deprecations, but will not introduce breaking changes without notice.
API Version | HuskSync Versions | Supported |
---|---|---|
v3.x | v3.0—Current | ✅ |
v2.x | v2.0—v2.2.8 | ❌ |
v1.x | v1.0—v1.4.1 | ❌️ |
Note:For versions older thanv3.3
, the HuskSync API was only distributed for the Bukkit platform (asnet.william278:husksync
)
The HuskSync API is available for the following platforms:
bukkit
- Bukkit, Spigot, Paper, etc. Provides Bukkit API event listeners and adapters to org.bukkit
objects.fabric
- Fabric API for Minecraft. Provides Fabric API event listeners and adapters to net.minecraft
objects.common
- Common API for all platforms.v3.3
; the artifact ID was net.william278:husksync
instead of net.william278.husksync:husksync-PLATFORM
.v2.2.5
are distributed on JitPack, and you will need to use the https://jitpack.io
repository instead.Add the repository to your pom.xml
as per below. You can alternatively specify /snapshots
for the repository containing the latest development builds (not recommended).
<repositories>
<repository>
<id>william278.net</id>
<url>https://repo.william278.net/releases</url>
</repository>
</repositories>
Add the dependency to your pom.xml
as per below. Replace HUSKSYNC_VERSION
with the latest version of HuskSync (without the v): . and MINECRAFT_VERSION
with the version of Minecraft you want to target (e.g. 1.20.1
). A correctly formed version target should look like: 3.7+1.20.1
. Omit the plus symbol and Minecraft version if you are targeting the common
platform.
<dependency>
<groupId>net.william278.husksync</groupId>
<artifactId>husksync-PLATFORM</artifactId>
<version>HUSKSYNC_VERSION+MINECRAFT_VERSION</version>
<scope>provided</scope>
</dependency>
Add the dependency as per below to your build.gradle
. You can alternatively specify /snapshots
for the repository containing the latest development builds (not recommended).
allprojects {
repositories {
maven { url 'https://repo.william278.net/releases' }
}
}
Add the dependency as per below. Replace HUSKSYNC_VERSION
with the latest version of HuskSync (without the v): . and MINECRAFT_VERSION
with the version of Minecraft you want to target (e.g. 1.20.1
). A correctly formed version target should look like: 3.7+1.20.1
. Omit the plus symbol and Minecraft version if you are targeting the common
platform.
dependencies {
compileOnly 'net.william278.husksync:husksync-PLATFORM:HUSKSYNC_VERSION+MINECRAFT_VERSION'
}
softdepend
(if you want to optionally use HuskSync) or depend
(if your plugin relies on HuskSync) section in plugin.yml
of your project.name: MyPlugin
version: 1.0
main: net.william278.myplugin.MyPlugin
author: William278
description: 'A plugin that hooks with the HuskSync API!'
softdepend: # Or, use 'depend' here
- HuskSync
ClassNotFoundException
spublic class HuskSyncAPIHook {
public HuskSyncAPIHook() {
// Ready to do stuff with the API
}
}
public class MyPlugin extends JavaPlugin {
public HuskSyncAPIHook huskSyncAPIHook;
@Override
public void onEnable() {
if (Bukkit.getPluginManager().getPlugin("HuskSync") != null) {
this.huskSyncAPIHook = new HuskSyncAPIHook();
}
}
}
HuskSyncAPI#getInstance()
BukkitHuskSyncAPI#getBukkitInstance()
to get the Bukkit-extended API instance (recommended)import net.william278.husksync.api.HuskSyncAPI;
public class HuskSyncAPIHook {
private final HuskSyncAPI huskSyncAPI;
public HuskSyncAPIHook() {
this.huskSyncAPI = HuskSyncAPI.getInstance();
}
}
CompletableFuture
s and Optional
s.CompletableFuture
is an asynchronous callback mechanism. The method will be processed asynchronously and the data returned when it has been retrieved. Then, use CompletableFuture#thenAccept(data -> {})
to do what you want to do with the data
you requested after it has asynchronously been retrieved, to prevent lag.Optional
is a null-safe representation of data, or no data. You can check if the Optional is empty via Optional#isEmpty()
(which will be returned by the API if no data could be found for the call you made). If the optional does contain data, you can get it via Optional#get()
.Warning:You should never call#join()
on futures returned from the HuskSyncAPI as futures are processed on server asynchronous tasks, which could lead to thread deadlock and crash your server if you attempt to lock the main thread to process them.
Now that you've got everything ready, you can start doing stuff with the HuskSync API!