> For the complete documentation index, see [llms.txt](https://onic-studio.gitbook.io/solarplugins-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarshards/api-guide.md).

# API Guide

#### 1. Khai báo phụ thuộc Maven (Dependency)

Thêm kho lưu trữ và thông tin phụ thuộc vào tệp `pom.xml` của dự án của bạn:

```xml
<dependencies>
    <dependency>
        <groupId>com.OmhVN</groupId>
        <artifactId>solarshards</artifactId>
        <version>1.2-Beta-03</version>
        <scope>provided</scope>
    </dependency>
</dependencies>
```

#### 2. Cách lấy đối tượng API (API Instance)

Bạn có thể truy xuất API instance thông qua lớp tiện ích `SolarShardsProvider` (khuyên dùng) hoặc qua `ServicesManager` của Bukkit:

**Cách A: Sử dụng `SolarShardsProvider` (Nhanh nhất)**

```java
import com.OmhVN.solarshards.api.SolarShardsAPI;
import com.OmhVN.solarshards.api.SolarShardsProvider;

SolarShardsAPI api = SolarShardsProvider.getAPI();
if (api != null) {
    // API đã sẵn sàng để sử dụng
}
```

**Cách B: Sử dụng Bukkit Services Manager**

```java
import com.OmhVN.solarshards.api.SolarShardsAPI;
import org.bukkit.Bukkit;
import org.bukkit.plugin.RegisteredServiceProvider;

RegisteredServiceProvider<SolarShardsAPI> rsp = Bukkit.getServicesManager().getRegistration(SolarShardsAPI.class);
if (rsp != null) {
    SolarShardsAPI api = rsp.getProvider();
    // API đã sẵn sàng để sử dụng
}
```

#### 3. Các phương thức API có sẵn

Vì các tác vụ ghi/đọc cơ sở dữ liệu trên Folia được thực hiện hoàn toàn bất đồng bộ, các phương thức bất đồng bộ (Async) được đặc biệt khuyến khích sử dụng cho người chơi không trực tuyến.

| Phương thức                                         | Mô tả                                                                                                 |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `long getShards(UUID uuid)`                         | Lấy số dư hiện tại của người chơi. *(Sẽ block main thread nếu người chơi offline và chưa được cache)* |
| `CompletableFuture<Long> getShardsAsync(UUID uuid)` | Lấy số dư bất đồng bộ từ cơ sở dữ liệu. *(Khuyên dùng cho người chơi offline)*                        |
| `void setShards(UUID uuid, long amount)`            | Đặt trực tiếp số dư shards cho người chơi (Tự động giới hạn theo max-shards).                         |
| `void addShards(UUID uuid, long amount)`            | Cộng thêm số lượng shards cho người chơi.                                                             |
| `void takeShards(UUID uuid, long amount)`           | Trừ bớt số lượng shards của người chơi.                                                               |
| `boolean canAddShards(UUID uuid, long amount)`      | Kiểm tra xem việc cộng thêm `amount` shards có làm người chơi vượt giới hạn max-shards hay không.     |
| `long getMaxShards()`                               | Lấy giới hạn số lượng shards tối đa được thiết lập trong cấu hình.                                    |

**Ví dụ: Truy vấn số dư bất đồng bộ (Async)**

```java
api.getShardsAsync(playerUUID).thenAccept(shards -> {
    player.sendMessage("Số dư shards của bạn lấy từ DB bất đồng bộ là: " + shards);
}).exceptionally(ex -> {
    ex.printStackTrace();
    return null;
});
```