### Async shard balance query example

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarshards/api-guide.md

Example of using getShardsAsync to retrieve a player's shard balance asynchronously. The callback sends a message to the player, and exceptions are printed to the stack trace.

```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;
});
```

--------------------------------

### RtpAPI methods

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/api-guide.md

Methods to start RTP, find random locations asynchronously, check status, manage cooldowns, and get world configuration.

```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 practical example

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/api-guide.md

Shows top 5 richest players and manual transfer without /pay command.

```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);
}
```

--------------------------------

### Initialize SolarCore API

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/api-guide.md

Obtain the SolarCoreAPI instance to start using the plugin's features.

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

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

--------------------------------

### Query documentation with ask parameter

Source: https://onic-studio.gitbook.io/solarplugins-docs/llms.txt

Use this HTTP GET request to query the documentation index with the `ask` parameter (required) and optional `goal` parameter. The response contains a direct answer with relevant excerpts and sources.

```http
GET https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarchat.md?ask=<question>&goal=<end_goal>
```

--------------------------------

### Get BalanceAPI instance

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/api-guide.md

Retrieves the BalanceAPI instance from SolarCoreAPI.

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

--------------------------------

### SolarWorth Integration Example

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarworth/api-guide.md

Demonstrates how to use PriceAPI, HistoryAPI, and category multipliers to display worth information to a player. Ensure SolarWorth is set as a dependency in your plugin.yml if calling the API on startup.

```java
import org.bukkit.entity.Player;
import org.bukkit.inventory.ItemStack;
import org.omhvn.solarworth.api.HistoryAPI;
import org.omhvn.solarworth.api.PriceAPI;
import org.omhvn.solarworth.api.SolarWorthAPI;

public class SolarWorthHook {

    public void displayWorthInfo(Player player) {
        // 1. Kiểm tra giá vật phẩm đang cầm trên tay
        ItemStack item = player.getInventory().getItemInMainHand();
        PriceAPI priceAPI = SolarWorthAPI.get().price();

        if (priceAPI.hasPrice(item)) {
            double price = priceAPI.getPrice(item);
            player.sendMessage("§aVật phẩm bạn đang cầm có giá bán là: §e$" + price + " §amỗi đơn vị.");
        } else {
            player.sendMessage("§cVật phẩm này không có giá trị bán lẻ.");
        }

        // 2. Kiểm tra tổng số tiền người chơi đã tích lũy
        HistoryAPI historyAPI = SolarWorthAPI.get().history();
        double totalEarnings = historyAPI.getTotalEarnings(player);
        player.sendMessage("§aTổng số tiền bạn đã bán được qua hệ thống từ trước đến nay: §e$" + totalEarnings);

        // 3. Tra cứu multiplier của danh mục ores
        double oreMultiplier = SolarWorthAPI.get().category().getMultiplier(player, "ores");
        player.sendMessage("§aMultiplier bán quặng hiện tại của bạn: §e" + oreMultiplier + "x");
    }
}
```

--------------------------------

### SpawnAPI methods

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/api-guide.md

Methods to check, get, set, delete, and teleport to spawns, plus counting players near a 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);
```

--------------------------------

### BalanceAPI transfer and config

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/api-guide.md

Methods to pay with tax and notifications, and get tax rate, min, and max amounts.

```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
```

--------------------------------

### Get SusAPI instance

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/api-guide.md

Retrieves the SusAPI instance from SolarCoreAPI.

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

--------------------------------

### Initialize SolarWorthAPI

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarworth/api-guide.md

Access the main API instance and its sub-components.

```java
// Lấy instance của API chính
SolarWorthAPI api = SolarWorthAPI.get();

PriceAPI    priceApi    = api.price();
CategoryAPI categoryApi = api.category();
HistoryAPI  historyApi  = api.history();
ToggleAPI   toggleApi   = api.toggle();
```

--------------------------------

### Initialize HomeAPI

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/api-guide.md

Access the HomeAPI instance from the main SolarCoreAPI.

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

--------------------------------

### Get RtpAPI instance

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/api-guide.md

Retrieves the RtpAPI instance from SolarCoreAPI.

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

--------------------------------

### Get SpawnAPI instance

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/api-guide.md

Retrieves the SpawnAPI instance from SolarCoreAPI.

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

--------------------------------

### Create Arena

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarduels/arena-map.md

Initialize the arena with a specific name.

```text
/dd create <tên>
```

--------------------------------

### Get WarpAPI instance

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/api-guide.md

Retrieves the WarpAPI instance from SolarCoreAPI.

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

--------------------------------

### SolarDuelsAPI.getInstance()

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarduels/api-guide.md

Lấy instance của SolarDuelsAPI để truy cập các phương thức chính của plugin.

```APIDOC
## SolarDuelsAPI.getInstance()

### Description
Lấy instance của SolarDuelsAPI để truy cập các phương thức chính của plugin.

### Method
`getInstance()`

### Return Value
- `SolarDuelsAPI` - Instance của API.

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

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

--------------------------------

### WarpAPI methods

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/api-guide.md

Methods to check, get, set, delete, and teleport to warps.

```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");
```

--------------------------------

### BalanceAPI leaderboard

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/api-guide.md

Methods to get top balances and a player's rank asynchronously.

```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);
    }
});
```

--------------------------------

### Initialize TpaAPI

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/api-guide.md

Access the TpaAPI instance from the main SolarCoreAPI.

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

--------------------------------

### BalanceAPI balance operations

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/api-guide.md

Methods to get balance, check funds, withdraw, and deposit.

```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);
```

--------------------------------

### SusAPI methods

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/api-guide.md

Methods to record flags, get sorted suspicious entries, and invalidate cache.

```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();
```

--------------------------------

### Cấu hình hệ thống config.yml

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/cau-hinh-chung.md

File cấu hình chính cho SolarCore, bao gồm các thiết lập debug, placeholders, thông báo và kết nối cơ sở dữ liệu.

```yaml
config-version: 1.0
enable-debug: false

placeholders:
  ON: "&a&lON"
  OFF: "&c&lOFF"

messages:
  action-bar-messages: true
  chat-messages: true
  use-action-bar-only: false

override-essentials: true   # Ghi đè lệnh /tpa, /tpahere của Essentials

database:
  type: "SQLITE"            # YAML | SQLITE | MYSQL
  sqlite:
    file: "solar_core.db"
  mysql:
    host: "localhost"
    port: 3306
    database: ""
    user: ""
    password: ""
    max-pool: 15
    use-ssl: false
```

--------------------------------

### Spawn module configuration (modules/spawn.yml)

Source: https://onic-studio.gitbook.io/solarplugins-docs/plugins/solarcore/cau-hinh-chung.md

YAML configuration for the Spawn module. Enables spawn teleportation on first join, on join, and on death, with a teleport countdown and optional GUI for selecting among multiple spawn points.

```yaml
spawn:
  enabled: true
  on-first-join: true       # Teleport về spawn lần đầu vào server
  on-join: true             # Teleport về spawn mỗi lần vào server
  on-death: true            # Teleport về spawn khi hồi sinh
  teleport-countdown: 5     # Giây đếm ngược

  gui:
    enabled: true           # Bật GUI chọn spawn (khi có nhiều spawn)
```