> 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/solarworth/api-guide.md). # API Guide SolarWorth tách toàn bộ API công khai vào package `org.omhvn.solarworth.api`. `SolarWorthAPI` là điểm truy cập duy nhất cho các API thành phần. ### Khởi đầu với `SolarWorthAPI` ```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(); ``` ### `PriceAPI` `PriceAPI` dùng để tra cứu và cập nhật giá vật phẩm. ```java public final class PriceAPI { // Lấy giá bán của ItemStack, gồm enchant, potion và các cộng dồn khác public double getPrice(ItemStack item); // Lấy giá bán cơ bản của một Material public double getPrice(Material material); // Lấy giá bán qua khóa String public double getPrice(String materialKey); // Kiểm tra ItemStack có giá bán không public boolean hasPrice(ItemStack item); // Kiểm tra Material có giá bán không public boolean hasPrice(Material material); // Lấy toàn bộ bảng giá đã đăng ký public Map getAllPrices(); // Đặt giá trực tiếp cho một khóa vật phẩm // Giá <= 0 sẽ xóa giá khỏi hệ thống public void setPrice(String materialKey, double price); // Lấy tổng số vật phẩm đã được định giá public int getPriceCount(); } ``` ### `CategoryAPI` `CategoryAPI` cung cấp dữ liệu danh mục, tiến trình và multiplier. ```java public final class CategoryAPI { // Lấy tất cả danh mục đang hoạt động public Collection getAll(); // Tìm danh mục theo ID, ví dụ: "ores" hoặc "crops" public Category getById(String id); // Tìm danh mục theo Material public Category findByMaterial(Material material); // Lấy tổng tiền đã bán trong một danh mục public double getTotal(UUID uuid, String categoryId); public double getTotal(Player player, String categoryId); // Lấy multiplier hiện tại của người chơi trong danh mục public double getMultiplier(UUID uuid, String categoryId); public double getMultiplier(Player player, String categoryId); // Lấy mốc doanh thu kế tiếp để lên multiplier tiếp theo // Trả về -1 nếu người chơi đã đạt mốc cao nhất public double getNextRequirement(UUID uuid, String categoryId); // Lấy tổng số danh mục đang có public int getCategoryCount(); } ``` ### `HistoryAPI` `HistoryAPI` cung cấp lịch sử bán hàng và thống kê doanh thu. ```java public final class HistoryAPI { // Lấy tổng doanh thu trọn đời của người chơi public double getTotalEarnings(UUID uuid); public double getTotalEarnings(Player player); // Lấy top người chơi bán được nhiều tiền nhất // Giới hạn tối đa 50 kết quả public List> getTopSellers(int limit); // Lấy toàn bộ lịch sử giao dịch của người chơi public List getHistory(UUID uuid); // Lấy số lượng giao dịch đã thực hiện public int getHistoryCount(UUID uuid); // Ghi nhận thủ công một giao dịch bán hàng public void recordSale(UUID uuid, String playerName, double amount, int itemCount, Material material, ItemStack item); public void recordSale(Player player, double amount, int itemCount, Material material); } ``` ### `SellRecord` `SellRecord` đại diện cho một bản ghi giao dịch bán hàng. ```java public class SellRecord { public String getFormatted(); public Material getMaterial(); public double getTotal(); public double getPricePerItem(); public long getTimestamp(); public String getEnchantStr(); public int getCount(); public String getDisplayName(); } ``` #### Ý nghĩa các getter | Phương thức | Mô tả | | ------------------- | -------------------------------------------- | | `getFormatted()` | Chuỗi giao dịch đã định dạng màu. | | `getMaterial()` | Loại vật phẩm đã bán. | | `getTotal()` | Tổng doanh thu của giao dịch. | | `getPricePerItem()` | Giá của một đơn vị vật phẩm. | | `getTimestamp()` | Thời điểm giao dịch, dạng epoch millisecond. | | `getEnchantStr()` | Chuỗi mô tả enchant của vật phẩm, nếu có. | | `getCount()` | Số lượng vật phẩm đã bán. | | `getDisplayName()` | Tên hiển thị tùy chỉnh của vật phẩm. | ### `ToggleAPI` `ToggleAPI` kiểm soát hiển thị lore giá trị ảo theo từng người chơi. ```java public final class ToggleAPI { // Kiểm tra người chơi có đang ẩn lore giá trị ảo không public boolean isHidden(Player player); // Đặt trạng thái ẩn hoặc hiện lore public void setHidden(Player player, boolean hidden); // Đảo trạng thái hiện tại public void toggle(Player player); } ``` ### Ví dụ tích hợp hoàn chỉnh ```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"); } } ``` {% hint style="info" %} Nếu plugin của bạn gọi API ngay khi khởi động, hãy đảm bảo SolarWorth đã được nạp trước bằng `depend` hoặc `softdepend` trong `plugin.yml`. {% endhint %}