-
-
Notifications
You must be signed in to change notification settings - Fork 128
API v2
github-actions[bot] edited this page Sep 20, 2023
·
1 revision
Warning: API v2 is no longer supported or compatible with HuskSync v3.0. See Data Snapshot API for the equivalent v3 API. 🚨
HuskSync v2.0 provides an API for fetching and retrieving UserData
; a snapshot of a user's synchronization.
This page assumes you've read the general API introduction and imported HuskSync (v2.x) into your project, and added it as a dependency.
🚨 HuskSync API v2 only targets HuskSync v2.0-2.2.8. It is not compatible with HuskSync v3.0+. The equivalent API for HuskSync v3 is the Data Snapshot API.
- Getting a user by UUID
- Getting a user's data
- Getting a user's inventory contents
- Updating a user's data
- HuskSync has a
User
object, representing a user saved in the database. You can retrieve a user usingHuskSyncAPI#getUser(uuid)
- If you have an online
org.bukkit.Player
object, you can useBukkitPlayer#adapt(player)
to get anOnlineUser
(extendsUser
), representing a logged-in user.
public class HuskSyncAPIHook {
private final HuskSyncAPI huskSyncAPI;
public HuskSyncAPIHook() {
this.huskSyncAPI = HuskSyncAPI.getInstance();
}
public void logUserName(UUID uuid) {
// getUser() returns a CompletableFuture supplying an Optional<User>
huskSyncAPI.getUser(uuid).thenAccept(optionalUser -> {
// Check if we found a user by that UUID either online or on the database
if (optionalUser.isEmpty()) {
// If we didn't, we'll log that they don't exist
System.out.println("User does not exist!");
return;
}
// The User object has two fields; uuid and username.
System.out.println("User name is: %s", optionalUser.get().username);
});
}
}
- With a
User
object, we can now callHuskSyncAPI#getUserData()
to fetch their latest data - The
UserData
object contains eight data "modules", each holding certain parts of information. - UserData does not have to contain any single data "module"; the modules contained in a given UserData object when user data is saved by the plugin are determined by the plugin config settings.
- You can fetch each module, which returns wrapped in an optional (empty if not present in the UserData object), via:
-
UserData#getStatus();
- The user's status (health, hunger, saturation, exp, game mode, etc) -
UserData#getInventory();
- The user's inventory contents. Contains a Base 64 serializedItemStack
array. -
UserData#getEnderChest();
- The user's ender chest contents. Contains a Base 64 serializedItemStack
array. -
UserData#getPotionEffects();
- The user's active potion effects. Contains a Base 64 serializedPotionEffect
array. -
UserData#getAdvancements();
- List of a user's advancements and mapped awarded criteria -
UserData#getStatistics();
- The user's statistics data containing four categories (untyped, items, blocks and entities) -
UserData#getLocation();
- The user's location data, for servers that have location syncing turned on. -
UserData#getPersistentDataContainer();
- The user's peristent data container, containing a map of keys to strings
-
public class HuskSyncAPIHook {
// ... //
public void logUserData(UUID uuid) {
huskSyncAPI.getUser(uuid).thenAccept(optionalUser -> {
// Optional#isPresent() is the opposite of #isEmpty()
if (optionalUser.isPresent()) {
logHealth(optionalUser.get());
}
});
}
private void logHealth(User user) {
// A user might not have data, if it's deleted by an admin or they're brand new
huskSyncAPI.getUserData(user).thenAccept(optionalUserData -> {
if (optionalUserData.isPresent()) {
// Get the StatusData from the UserData object
Optional<StatusData> statusData = optionalUserData.get().getStatus();
// Print the health from the fields, if the user has a status object
statusData.ifPresent(status -> {
System.out.println("%s's health: %d/%d", user.username, status.health, status.maxHealth);
});
}
});
}
}
- The API provides methods for deserialzing
ItemData
used to hold Base 64 serialized inventory and ender chestItemStack
array contents into actualItemStack
array data. - For deserialziing inventories, use
HuskSyncAPI#deserializeInventory(serializedItems)
- For deserialziing ender chests, use
HuskSyncAPI#deserializeItemStackArray(serializedItems)
- Alternatively, the
HuskSyncAPI#getPlayerInventory(user)
andHuskSyncAPI#getPlayerEnderChest(user)
methods will do this for you nice and easily. Note though if the last UserData module does not contain UserData, the ItemData returned here will be representative of an empty ItemStack array. - Serialization and deserialization methods are also available for Potion Effects.
public class HuskSyncAPIHook {
// ... //
private void printInventoryItems(User user) {
huskSyncAPI.getUserData(user).thenAccept(optionalUserData -> {
if (optionalUserData.isPresent()) {
// Get the ItemData and make sure it's present
Optional<ItemData> inventoryDataOptional = optionalUserData.get().getInventory();
if (inventoryDataOptional.isEmpty) {
return;
}
ItemData inventoryData = inventoryDataOptional.get();
// Get the ItemStack[] array as a BukkitInventoryMap.
// This returns a future, but we're using #join() to block the thread until it's done
BukkitInventoryMap inventory = huskSyncAPI.deserializeInventory(inventoryData.serializedItems).join();
// A BukkitInventoryMap is simply a wrapper for an ItemStack array.
// It provides a few handy methods for getting the player's armor, their offhand item, etc.
// To get the ItemStack array from it, just call BukkitInventoryMap#getContents();
for (ItemStack item : inventory.getContents()) {
// Print out the item material types of every item in the player's inventory
System.out.println(item.getType().name());
}
}
});
}
}
HuskSyncAPI#getPlayerInventory()
private void printInventoryItems(User user) {
huskSyncAPI.getPlayerInventory(user).thenAccept(inventory -> {
if (inventory.isPresent()) {
for (ItemStack item : inventory.get().getContents()) {
System.out.println(item.getType().name());
}
}
});
}
HuskSyncAPI#getPlayerEnderChest()
private void printEnderChestItems(User user) {
huskSyncAPI.getPlayerEnderChest(user).thenAccept(enderChest -> {
if (enderChest.isPresent()) {
for (ItemStack item : enderChest.get()) {
System.out.println(item.getType().name());
}
}
});
}
- You can use
HuskSyncAPI#setUserData(user, userData)
to set a user's modified data to the database. - If you need to modify user data every time it's updated, you may want to look at listening to one of HuskSync's provided events instead.
- You can use
HuskSyncAPI#serializeItemStackArray(itemStack[])
to serialize an array of ItemStacks into Base 64. - Alternatively, you can use
HuskSyncAPI#setInventoryData(user, bukkitInventoryMap)
to set a user's inventory, orHuskSyncAPI#setEnderChestData(user, itemStack[])
to set a user's ender chest. - Updating UserData will overwrite the player's current "live" data. HuskSync does not track the player's "live" data constantly by design, only "snapshots" of their data when it is saved. In other words, getting and updating a user's data may actually end up rolling them back.
public class HuskSyncAPIHook {
// Set a user's health to 20
private void updateUserHealth(User user) {
huskSyncAPI.getUserData(user).thenAccept(optionalUserData -> {
if (optionalUserData.isPresent()) {
UserData data = optionalUserData.get();
Optional<StatusData> statusDataOptional = data.getStatus();
StatusData statusData = statusDataOptional.get();
statusData.health = 20;
// This returns a CompletableFuture<Void> that will invoke #thenRun() when it has completed
huskSyncAPI.setUserData(user, data).thenRun(() -> {
System.out.println("Healed %s!", user.username);
});
}
});
}
}
This documentation is available via william278.net |
---|
- 📚 Setup
- 📄 Config File
- 🔗 Troubleshooting
- ↪️ Data Rotation
↗️ Legacy Migration- ✨ MPDB Migration
- 🎏 Translations
- ❓ FAQs
- 🖥️ Commands
- ✅ Sync Features
- ⚙️ Sync Modes
- 🟩 Plan Hook
- ☂️ Dumping UserData
- 📋 Event Priorities
- ⚔️ Keep Inventory
- 📦 API v3
- 🕸️ API v2 (Legacy)
- 💻 GitHub
- 📂 Buy HuskSync
- 🚰 Spigot
- 🛒 Polymart
- ⚒️ BuiltByBit
- 💬 Discord Support