> 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/solarduels/api-guide.md).

# API Guide

SolarDuels cung cấp API Java và custom events để plugin khác có thể tích hợp trực tiếp.

### Lấy API instance

```java
import org.OmhVN.api.SolarDuelsAPI;

SolarDuelsAPI api = SolarDuelsAPI.getInstance();
```

### Các phương thức chính

| Phương thức                          | Mô tả                                                      |
| ------------------------------------ | ---------------------------------------------------------- |
| `getPlayerStats(UUID uuid)`          | Lấy thống kê người chơi.                                   |
| `savePlayerStats(PlayerStats stats)` | Lưu lại thống kê người chơi.                               |
| `isInDuel(UUID uuid)`                | Kiểm tra người chơi có đang trong trận không.              |
| `getActiveDuel(UUID uuid)`           | Lấy trận hiện tại của người chơi. Trả `null` nếu không có. |
| `isInQueue(UUID uuid)`               | Kiểm tra người chơi có đang trong hàng chờ không.          |
| `getQueueWaitTime(UUID uuid)`        | Lấy thời gian chờ trong queue, tính bằng giây.             |
| `isSpectating(UUID uuid)`            | Kiểm tra người chơi có đang spectate không.                |
| `getTopPlayers(int limit)`           | Lấy danh sách người chơi hàng đầu theo số trận thắng.      |

### Custom events

#### `DuelStartEvent`

Sự kiện này chạy trước khi trận đấu bắt đầu.

* `getPlayer1()` — người chơi thứ nhất.
* `getPlayer2()` — người chơi thứ hai.
* `getArena()` — đấu trường được dùng.
* `getTimeLimit()` — thời gian trận đấu, tính bằng giây.
* Có thể hủy bằng `setCancelled(true)`.

#### `DuelEndEvent`

Sự kiện này chạy ngay khi trận đấu kết thúc.

* `getPlayer1()` — người chơi thứ nhất.
* `getPlayer2()` — người chơi thứ hai.
* `getWinner()` — người thắng. Trả `null` nếu hòa hoặc bị hủy.
* `getLoser()` — người thua. Trả `null` nếu hòa hoặc bị hủy.
* `getArena()` — đấu trường đã dùng.
* `getDuel()` — dữ liệu chi tiết của trận.

#### `PlayerJoinQueueEvent`

Sự kiện này chạy khi người chơi vào hàng chờ.

* `getPlayer()` — người chơi tham gia queue.
* Có thể hủy bằng `setCancelled(true)`.

#### `PlayerLeaveQueueEvent`

Sự kiện này chạy khi người chơi rời hàng chờ.

* `getPlayer()` — người chơi rời queue.

### Ví dụ lắng nghe sự kiện

```java
import org.OmhVN.api.events.DuelStartEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class MyDuelListener implements Listener {
    @EventHandler
    public void onDuelStart(DuelStartEvent event) {
        String p1 = event.getPlayer1().getName();
        String p2 = event.getPlayer2().getName();
        String arenaName = event.getArena().getName();

        event.getPlayer1().sendMessage("§6§l⚔ Trận đấu với " + p2 + " tại " + arenaName + " đang bắt đầu!");
        event.getPlayer2().sendMessage("§6§l⚔ Trận đấu với " + p1 + " tại " + arenaName + " đang bắt đầu!");
    }
}
```

### Tích hợp SolarElo

Khi chạy cùng SolarElo, SolarDuels có thể đồng bộ ELO qua cấu hình `USE-SOLARELO` trong `config.yml`.

Khi bật tích hợp:

* Placeholder ELO sẽ lấy dữ liệu từ SolarElo.
* Matchmaking sẽ dùng ELO của SolarElo.
* Xếp hạng trong `ranks.yml` sẽ dựa trên điểm đã đồng bộ.
* Kết quả trận đấu sẽ cập nhật ELO qua API của SolarElo.

{% hint style="info" %}
Nếu plugin của bạn gọi API ngay khi khởi động, hãy đảm bảo SolarDuels đã được nạp trước bằng `depend` hoặc `softdepend` trong `plugin.yml`.
{% endhint %}