HuskSync v3.0 provides an API for getting, creating, editing and deleting `DataSnapshot`s; a snapshot of a user at a given moment in time. This page will walk you through how to manipulate delete snapshots using the HuskSync API.
This page assumes you have read the general [[API]] introduction and that you have both imported HuskSync (v3.x) into your project and added it as a dependency.
## Table of Contents
1. [Getting a User](#1-getting-a-user)
2. [Getting DataSnapshots for a User](#2-getting-datasnapshots-for-a-user)
1. [Getting a User's current data](#21-getting-a-users-current-data)
2. [Getting a User's latest saved DataSnapshot](#22-getting-a-users-latest-saved-datasnapshot)
3. [Getting a list of a User's saved DataSnapshots](#23-getting-a-list-of-a-users-saved-datasnapshots)
3. [Packing and Unpacking DataSnapshots](#3-packing-and-unpacking-datasnapshots)
4. [Getting and setting data in a DataSnapshot](#4-getting-and-setting-data-in-a-datasnapshot)
1. [Data Types](#41-data-types)
2. [Editing Health, Hunger, Experience, and GameMode data](#42-editing-health-hunger-experience-and-gamemode-data)
3. [Editing Inventory and Ender Chest data](#43-editing-inventory-and-ender-chest-data)
* If you have an online `org.bukkit.Player` object, you can use `BukkitPlayer#adapt(player)` to get an `OnlineUser` (extends `User`), representing a logged-in user.
<details>
<summary>Code Example — Getting an online user</summary>
* HuskSync provides a method for getting the user's current data. `HuskSyncAPI#getCurrentData(User)` returns a `CompletableFuture` supplying an `Optional<DataSnapshot.Unpacked>`.
* This method will get the user's current data if they are online on the network, or their last saved data if they are offline (or, an empty optional if they user has never logged on).
<details>
<summary>Code Example — Getting a user's current DataSnapshot</summary>
### 2.3 Getting a list of a User's saved DataSnapshots
* If you want to get a list of all of a user's saved snapshots, you can use `HuskSyncAPI#getSnapshots(User)`. This method returns a `CompletableFuture` supplying an `Optional<List<DataSnapshot.Unpacked>>`.
<details>
<summary>Code Example — Getting all of a user's saved DataSnapshots</summary>
* HuskSync provides two types of `DataSnapshot` objects: `DataSnapshot.Packed` and `DataSnapshot.Unpacked`.
-`DataSnapshot.Packed` is a snapshot that has had its data serialized into a byte map. This snapshot is ready to be saved in the database or set to Redis.
-`DataSnapshot.Unpacked` is a snapshot that has been unpacked from a `DataSnapshot.Packed` object. You can get, set, and manipulate data from these snapshots.
* Most of the time, you won't need to worry about this, as HuskSync typically deals with `Unpacked` snapshots. However, if you need to convert between the two (e.g., if you wish to copy the snapshot), you can use the `HuskSyncAPI#packSnapshot(DataSnapshot.Unpacked)` and `HuskSyncAPI#unpackSnapshot(DataSnapshot.Packed)` methods.
* The editor method `HuskSyncAPI#editPackedSnapshot(DataSnapshot.Packed, Consumer<DataSnapshot.Unpacked>)` additionally provides a utility for unpacking, editing, then repacking a packed `DataSnapshot` object.
<details>
<summary>Code Example — Packing and unpacking snapshots</summary>
* Data within `DataSnapshot`s is represented by `Data` objects of different types; `Data.Items.Inventory` represents Inventory data, `Data.Health` represents a user's current/max health, `Data.Hunger` represents a user's current/max hunger, and so on.
* On Bukkit servers, `BukkitData` classes implement `Data` classes and provide utilities for converting between `Bukkit` and `HuskSync` data types.
*`DataSnapshot.Unpacked` provides methods for getting and setting `Data` in the snapshot, such as `DataSnapshot.Unpacked#getInventory()` (which returns an `Optional`) and `DataSnapshot.Unpacked#setHealth(Data.Health)`.
### 4.1 Data Types
| Identifier Key | Description | Get Method | Set Method |
| `husksync:experience` | User level, experience, and score | `#getExperience` | `#setExperience` |
| `husksync:game_mode` | User game mode and flight status | `#getGameMode` | `#setGameMode` |
| `husksync:persistent_data` | User persistent data container | `#getPersistentData` | `#setPersistentData` |
| Custom types; `plugin:foo` | Any custom data | `#getData(Identifer)` | `#setData(Identifier)` |
* Plugin developers may supply their own `Data` classes for synchronisation & saving by implementing the `Data` interface and registering a `Serializer<>` for their class to an `Identifier`. See the [[Custom Data API]] page for more information.
* You can only get data from snapshots where a serializer has been registered for it on this server and, in the case of the built-in data types, where the sync feature has been enabled in the [[Config File]]. If you try to get data from a snapshot where the data type is not supported, you will get an empty `Optional`.
### 4.2 Editing Health, Hunger, Experience, and GameMode data
*`DataSnapshot.Unpacked#getHealth()` returns an `Optional<Data.Health>`, which you can then use to get the player's current and max health.
*`DataSnapshot.Unpacked#setHealth(Data.Health)` sets the player's current and max health. You can create a `Health` instance to pass on the Bukkit platform through `BukkitData.Health.from(double, double, double)`.
* Similar methods exist for Hunger, Experience, and GameMode data types
* Once you've updated the data in the snapshot, you can save it to the database using `HuskSyncAPI#setCurrentData(user, userData)`.
<details>
<summary>Code Example — Getting and setting a player's health</summary>
// Save the snapshot - This will update the player if online and save the snapshot to the database
huskSyncAPI.setCurrentData(user, snapshot);
});
```
</details>
* To make this code more concise, we can use the `HuskSyncAPI#editCurrentData()` method to get the user's current data and perform an operation in a `Consumer` class.
* The result of editing the `DataSnapshot` object in the `Consumer` is then automatically passed to `HuskSyncAPI#setCurrentData()` to save the snapshot to the database and update the user if they are online
<details>
<summary>Code Example — Editing a player's health</summary>
* We can get a player's inventory using `DataSnapshot.Unpacked#getInventory()`, which returns an `Optional<Data.Items.Inventory>`. You can also get the player's Ender Chest inventory using `DataSnapshot.Unpacked#getEnderChest()`.
*`Data.Items.Inventory` provides methods for the player's inventory, armor, offhand, and ender chest items as platform-agnostic `Stack` objects, which lets you view basic Item information, but does not expose their full NBT data.
* On Bukkit, simply cast a `Data.Items.(Inventory/EnderChest)` to a `BukkitData.Items.(Inventory/EnderChest)` to get access to the Bukkit `ItemStack[]` contents of the player's items, allowing you to edit the contents.
<details>
<summary>Code Example — Getting and setting a player's inventory or Ender Chest</summary>
// Save the snapshot - This will update the player if online and save the snapshot to the database
huskSyncAPI.setCurrentData(user, snapshot);
});
```
</details>
* There also exist utility methods for both getting and setting just the player's current inventory or Ender Chest contents, if all you need to do is just update the player's inventory/Ender Chest.
* The Inventory methods are `#getCurrentInventory`, `#setCurrentInventory`, and `#editCurrentInventory`. For Ender chests, these are `#getCurrentEnderChest`, `#setCurrentEnderChest`, and `#editCurrentEnderChest`. There's also `Contents` methods that just deal with ItemStacks[], if you prefer.
<details>
<summary>Code Example — Editing a player inventory</summary>
* HuskSync's support for player Locations is intended for mirrored world instances (such as RPG servers), and so is disabled by default in the plugin config.
* We can get a player's location using `DataSnapshot.Unpacked#getLocation()`, which returns an `Optional<Data.Location>`.
*`Data.Location` provides methods for getting and setting the player's location, pitch, and yaw. We can also use the aforementioned `BukkitData` classes to set this using a `org.bukkit.Location`, and speed things along using the `HuskSyncAPI#editCurrentData` method.
<details>
<summary>Code Example — Editing a player's location</summary>
* Advancements can be retrieved using `DataSnapshot.Unpacked#getAdvancements()`, which returns an `Optional<Data.Advancements>`.
*`Data.Advancements` provides a wrapper for a list of `Data.Advancements.Advancement` objects, representing a map of a player's completed criteria when progressing to complete an advancement.
* You can add and remove advancements from the list, and set the list of advancements using `Data.Advancements#setAdvancements(List<Data.Advancements.Advancement>)`.
<details>
<summary>Code Example — Editing a player's advancements</summary>
* HuskSync provides methods for creating new snapshots; either by capturing a player's current data or by creating a new snapshot from scratch using a `DataSnapshot.Builder`.
### 5.1 Creating a new snapshot from a player's current data
* You can create a new snapshot from a player's current data using `HuskSyncAPI#createSnapshot(OnlineUser)`, which returns a `DataSnapshot.Packed` with a save cause of `SaveCause.API`.
<details>
<summary>Code Example — Capturing a player's current data into a Snapshot</summary>
```java
// Create a new snapshot from a player's current data
final DataSnapshot.Packed data = huskSyncAPI.createSnapshot(user);
// editPackedSnapshot() provides a utility for unpacking, editing, then repacking a DataSnapshot object
final DataSnapshot.Packed edited = huskSyncAPI.editPackedSnapshot(data, (unpacked) -> {
unpacked.setHealth(BukkitData.Health.from(10, 20, 20)); // Example - sets the user's health to 10 (5 hearts)
});
// Save the snapshot - This will save the snapshot to the database
huskSyncAPI.addSnapshot(edited);
```
</details>
### 5.2 Creating a new snapshot from scratch
* You can create a new snapshot from scratch using a `DataSnapshot.Builder`. This is useful if you want to create a custom snapshot with specific data and apply it to a user.
* Get a new `DataSnapshot.Builder` using `HuskSyncAPI#snapshotBuilder()`.
<details>
<summary>Code Example — Creating a new snapshot from scratch</summary>
```java
// Create a new snapshot from scratch
final DataSnapshot.Builder builder = huskSyncAPI.snapshotBuilder();
// Create an empty inventory with a diamond sword in the first slot
final BukkitData.Items.Inventory inventory = BukkitData.Items.Inventory.empty();
inventory.setContents(new ItemStack[] { new ItemStack(Material.DIAMOND_SWORD) });
inventory.setHeldItemSlot(0); // Set the player's held item slot to the first slot
// Use the builder to create, then pack, a new snapshot
final DataSnapshot.Packed packed = builder
.saveCause(SaveCause.API) // This is the default save cause, but you can change it if you want
.setTimestamp(OffsetDateTime.now().minusDays(3)) // Set the timestamp to 3 days ago
.setInventory(inventory) // Set the player's inventory
.setHealth(BukkitData.Health.from(10, 20, 20)) // Set the player to having 5 hearts
.buildAndPack(); // You can also call just #build() to get a DataSnapshot.Unpacked
// Save the snapshot - This will save the snapshot to the database for a User
huskSyncAPI.addSnapshot(user, packed);
```
</details>
## 6. Deleting DataSnapshots
* You can delete a snapshot using `HuskSyncAPI#deleteSnapshot(User, UUID)`, which will delete a snapshot from the database by its UUID.
* This method returns a CompletableFuture<Boolean> which will resolve to `true` if there was a snapshot with that UUID to delete, or `false` if there was no snapshot with that UUID to delete.
<details>
<summary>Code Example — Deleting a snapshot</summary>
