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

# API Guide

### Thêm dependency

```xml
<!-- pom.xml -->
<dependency>
    <groupId>org.omhvn</groupId>
    <artifactId>SolarCore</artifactId>
    <version>1.0-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>
```

Thêm `SolarCore` vào `depend` hoặc `softdepend` trong `plugin.yml`:

```yaml
depend: [SolarCore]
```

### Khởi tạo

```java
import org.omhvn.solarcore.api.SolarCoreAPI;

SolarCoreAPI api = SolarCoreAPI.get();
```

***

### TpaAPI

```java
TpaAPI tpa = SolarCoreAPI.get().tpa();
```

#### Trạng thái người chơi

```java
// Kiểm tra / đặt toggle TPA
tpa.isTpaEnabled(player);
tpa.setTpaEnabled(player, false);

// Kiểm tra / đặt toggle TPAHere
tpa.isTpaHereEnabled(player);
tpa.setTpaHereEnabled(player, true);

// Auto-accept
tpa.isAutoAcceptEnabled(player);
tpa.setAutoAcceptEnabled(player, true);
```

#### Gửi yêu cầu

```java
// Gửi /tpa (có kiểm tra đầy đủ)
RequestResult result = tpa.sendRequest(sender, target);

// Gửi /tpahere
RequestResult result = tpa.sendHereRequest(sender, target);

// Gửi bỏ qua mọi kiểm tra
tpa.sendRequestForce(sender, target, false);

// Chỉ kiểm tra mà không gửi
RequestResult valid = tpa.validate(sender, target, false);
```

#### Kết quả RequestResult

| Giá trị                    | Ý nghĩa                           |
| -------------------------- | --------------------------------- |
| `SUCCESS`                  | Thành công                        |
| `INVALID_PLAYER`           | Player null hoặc không hợp lệ     |
| `SELF_TELEPORT`            | Tự gửi cho mình                   |
| `BLACKLISTED_WORLD_SENDER` | World của người gửi bị blacklist  |
| `BLACKLISTED_WORLD_TARGET` | World của người nhận bị blacklist |
| `TPA_DISABLED`             | Người nhận đã tắt TPA             |
| `TPAHERE_DISABLED`         | Người nhận đã tắt TPAHere         |
| `ON_COOLDOWN`              | Đang trong thời gian chờ          |
| `DAILY_LIMIT_REACHED`      | Đã đạt giới hạn ngày              |
| `ALREADY_REQUESTED`        | Đã gửi yêu cầu rồi                |
| `REQUEST_CANCELLED`        | Yêu cầu bị hủy                    |

#### Chấp nhận / Từ chối

```java
// Chấp nhận yêu cầu từ sender
tpa.acceptRequest(target, sender);
tpa.acceptLatestRequest(target);      // Chấp nhận yêu cầu mới nhất
tpa.acceptAllRequests(target);        // Chấp nhận tất cả

// Từ chối
tpa.denyRequest(target, sender);
tpa.denyLatestRequest(target);
tpa.denyAllRequests(target);

// Hủy yêu cầu đã gửi
tpa.cancelRequest(sender, target);
tpa.cancelAllOutgoingRequests(sender);
tpa.cancelPendingTeleport(player);    // Hủy teleport đang đếm ngược
```

#### Truy vấn yêu cầu

```java
tpa.hasPendingRequest(target);                    // Có yêu cầu đang chờ không?
tpa.getPendingRequestCount(target);               // Số yêu cầu đang chờ
tpa.getPendingRequests(target);                   // List<TpaRequest>
tpa.getOutgoingRequests(sender);                  // Yêu cầu đang gửi
tpa.getRequest(sender, target);                   // Optional<TpaRequest>
tpa.hasRequestTo(sender, target);                 // Đã gửi cho target chưa?
tpa.hasPendingTeleport(player);                   // Đang chờ teleport không?
```

#### Cooldown & Giới hạn

```java
tpa.isOnCooldown(sender, target);
tpa.getRemainingCooldown(sender, target);         // milliseconds
tpa.getRemainingDailyLimit(sender, target);
```

#### Thông tin cấu hình

```java
tpa.getRequestExpirationTime();
tpa.getTeleportCountdown();
tpa.getCooldownTime();
tpa.getDailyLimit();
tpa.isWorldBlacklisted("world_nether");
```

***

### HomeAPI

```java
HomeAPI home = SolarCoreAPI.get().home();
```

```java
// Lấy danh sách home
Map<String, Location> homes = home.getHomes(player);
Location loc = home.getHome(player, "home");
boolean has = home.hasHome(player, "farm");

// Số lượng
int count = home.getHomeCount(player);
int max = home.getMaxHomes(player);
boolean canSet = home.canSetMoreHomes(player);

// Đặt / xóa home
SetHomeResult result = home.setHome(player, "base");     // Có kiểm tra giới hạn
home.setHomeForce(player, "base", location);             // Bỏ qua giới hạn
home.deleteHome(player, "base");

// Teleport
home.teleportHome(player, "home");

// Cooldown
home.isOnCooldown(player);
home.getRemainingCooldown(player);                       // milliseconds
home.setCooldown(player);

// Load/Unload dữ liệu
home.loadHomes(player);
home.unloadHomes(player);
```

***

### WarpAPI

```java
WarpAPI warp = SolarCoreAPI.get().warp();
```

```java
warp.exists("market");
warp.getWarp("market");                  // Location
warp.getWarpNames();                     // Set<String>
warp.getWarpCount();

warp.setWarp("market", location);
warp.deleteWarp("market");
warp.teleport(player, "market");
```

***

### SpawnAPI

```java
SpawnAPI spawn = SolarCoreAPI.get().spawn();
```

```java
spawn.hasSpawn();
spawn.hasSpawn(2);
spawn.getSpawnLocation();                // Spawn số 1
spawn.getSpawnLocation(2);              // Spawn số 2

spawn.setSpawn(1, location, player);
spawn.deleteSpawn(1, player);

spawn.teleport(player);                  // Teleport về spawn 1
spawn.teleport(player, 2);              // Teleport về spawn 2

// Đếm số người chơi gần spawn
int count = spawn.getPlayersNearSpawn(1, 50.0);
```

***

### RtpAPI

```java
RtpAPI rtp = SolarCoreAPI.get().rtp();
```

```java
// Bắt đầu RTP cho player
rtp.startRtp(player, "world");

// Tìm vị trí ngẫu nhiên (async)
rtp.findRandomLocation("world", new RtpAPI.LocationCallback() {
    @Override
    public void onSuccess(Location location) {
        player.teleport(location);
    }

    @Override
    public void onFail(RtpAPI.FailReason reason) {
        // MAX_ATTEMPTS_REACHED | WORLD_NOT_FOUND | NOT_CONFIGURED
    }
});

// Trạng thái
rtp.isActive(player);
rtp.getActiveCount();
rtp.getMaxActivePlayers();

// Cooldown
rtp.isOnCooldown(player, "world");
rtp.getRemainingCooldown(player, "world");  // milliseconds
rtp.setCooldown(player, "world");

// Thông tin cấu hình world
rtp.isWorldConfigured("world");
rtp.getMaxRadius("world");
rtp.getMinRadius("world");
rtp.getCooldown("world");
```

***

### BalanceAPI

```java
BalanceAPI balance = SolarCoreAPI.get().balance();
```

#### Kiểm tra

```java
// Vault + Economy plugin đã kết nối chưa
balance.isAvailable();
```

#### Số dư

```java
// Lấy số dư (online hoặc offline)
double bal = balance.getBalance(offlinePlayer);

// Kiểm tra đủ tiền không
boolean enough = balance.has(offlinePlayer, 1000.0);

// Trừ tiền trực tiếp (không thông báo, không tính thuế)
boolean success = balance.withdraw(offlinePlayer, 500.0);

// Cộng tiền trực tiếp (không thông báo)
balance.deposit(offlinePlayer, 500.0);
```

#### Chuyển tiền

```java
// Chuyển tiền — áp dụng thuế, gửi thông báo, ghi log theo config
balance.pay(payerPlayer, receiverPlayer, 1000.0);

// Thông tin cấu hình
double tax = balance.getTaxRate();   // 0.0 → 1.0
double min = balance.getMinAmount();
double max = balance.getMaxAmount(); // 0 = không giới hạn
```

#### Bảng xếp hạng

```java
// Top N người giàu nhất
balance.getTopBalances(10).thenAccept(list -> {
    for (BalanceAPI.BalanceEntry e : list) {
        e.uuid();
        e.name();
        e.balance();
    }
});

// Rank của một người chơi (trả -1 nếu không có trong danh sách)
balance.getBalanceRank(offlinePlayer).thenAccept(rank -> {
    if (rank == -1) {
        // Người chơi chưa có tiền hoặc chưa từng vào server
    } else {
        player.sendMessage("Rank của bạn: #" + rank);
    }
});
```

#### BalanceEntry

| Field       | Kiểu     | Mô tả           |
| ----------- | -------- | --------------- |
| `uuid()`    | `String` | UUID người chơi |
| `name()`    | `String` | Tên người chơi  |
| `balance()` | `double` | Số dư           |

#### Ví dụ thực tế

```java
// Hiển thị top 5 giàu nhất vào chat
BalanceAPI bal = SolarCoreAPI.get().balance();

if (!bal.isAvailable()) {
    player.sendMessage("§cEconomy chưa được cài đặt!");
    return;
}

bal.getTopBalances(5).thenAccept(list -> {
    player.sendMessage("§6§l--- Top 5 Giàu Nhất ---");
    for (int i = 0; i < list.size(); i++) {
        BalanceAPI.BalanceEntry e = list.get(i);
        player.sendMessage("§e#" + (i + 1) + " §f" + e.name() + " §7— §a" + e.balance());
    }
});

// Chuyển tiền thủ công không qua lệnh /pay
if (bal.has(payer, 500.0)) {
    bal.withdraw(payer, 500.0);
    bal.deposit(receiver, 500.0);
}
```

***

### SusAPI

API cho hệ thống theo dõi người chơi đáng ngờ (tích hợp anticheat).

```java
SusAPI sus = SolarCoreAPI.get().sus();
```

```java
// Ghi nhận flag từ anticheat
sus.recordFlag(uuid, playerName, "KillAura");

// Lấy danh sách người chơi sus
CompletableFuture<List<SusAPI.SusEntry>> future =
    sus.getSortedEntries(SusAPI.SortMode.BY_FLAGS);  // hoặc BY_RECENT

future.thenAccept(entries -> {
    for (SusAPI.SusEntry e : entries) {
        e.getUuid();
        e.getPlayerName();
        e.getTotalFlags();
        e.getTopCheck();         // Check bị flag nhiều nhất
        e.getFirstFlag();        // Timestamp đầu tiên
        e.getLastFlag();         // Timestamp gần nhất
        e.getCheckCounts();      // Map<String, Integer> chi tiết từng check
    }
});

// Xóa cache để load lại dữ liệu
sus.invalidateCache();
```

***

### BlockerAPI

API cho module chặn vật phẩm.

```java
BlockerAPI blocker = SolarCoreAPI.get().blocker();
```

```java
// Kiểm tra module có bật không
blocker.isModuleEnabled();

// Kiểm tra vật phẩm có bị chặn không
boolean blocked = blocker.isBlocked(player, Material.TNT, BlockerAPI.BlockAction.PLACE);

// Lấy thông tin chi tiết entry bị chặn
BlockerAPI.BlockEntry entry = blocker.findBlock(player, Material.TNT, BlockerAPI.BlockAction.PLACE);
if (entry != null) {
    entry.getKey();              // Key trong config (vd: "tnt")
    entry.getMaterial();
    entry.getDisplayName();
    entry.getMessage();
    entry.getBypassPermission();
}

// Lấy nội dung thông báo đã parse placeholder
String msg = blocker.buildMessage(entry, BlockerAPI.BlockAction.PLACE, player);
```

#### BlockAction

| Giá trị    | Mô tả                  |
| ---------- | ---------------------- |
| `HOLD`     | Cầm item trên tay      |
| `USE`      | Dùng item (click phải) |
| `INTERACT` | Tương tác              |
| `PICKUP`   | Nhặt item              |
| `DROP`     | Thả item               |