> 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/chuc-nang.md).

# Chức năng

### 1. Cấu hình cơ sở dữ liệu (`databases.yml`)

Cấu hình loại lưu trữ trong file `databases.yml`. Hỗ trợ 4 loại chính:

```yaml
# Loại database: sqlite, mysql, mariadb, mongodb
type: "sqlite"

# Cấu hình độc lập cho từng loại:
mysql:
  host: localhost
  port: 3306
  database: "solarworth"
  user: root
  password: ""
  max-pool: 15
  use-ssl: false

mariadb:
  host: localhost
  port: 3306
  database: "solarworth"
  user: root
  password: ""
  max-pool: 15
  use-ssl: false

mongodb:
  uri: "" # Nếu điền URI thì các trường dưới sẽ bị bỏ qua
  host: localhost
  port: 27017
  database: "solarworth"
  user: ""
  password: ""
```

***

### 2. Bảng giá và quy tắc định giá (`prices.yml`)

Bảng giá chính của các vật phẩm được lưu trữ tại `worth/prices.yml`. Plugin hỗ trợ một hệ thống định giá cực kỳ linh hoạt và thông minh:

#### 2.1. Định giá vật phẩm cơ bản

Định giá trực tiếp bằng Material ID của Minecraft:

```yaml
prices:
  DIAMOND: 20.0
  GOLD_INGOT: 5.0
  COAL: 1.0
```

#### 2.2. Định giá sách enchant

Định giá sách phù phép theo từng loại enchant và cấp độ riêng biệt bằng định dạng: `ENCHANTED_BOOK_<TÊN_ENCHANT_CHỮ_HOA>_<CẤP_ĐỘ>`.

```yaml
prices:
  ENCHANTED_BOOK_SHARPNESS_5: 1500.0
  ENCHANTED_BOOK_EFFICIENCY_5: 1420.0
  ENCHANTED_BOOK_MENDING_1: 200.0
```

#### 2.3. Cộng dồn giá trị enchant cho vật phẩm thông thường

Khi người chơi kiểm tra giá hoặc bán một vật phẩm có chứa enchant (ví dụ: một thanh kiếm Kim Cương có Sharpness 5), SolarWorth sẽ tự động tính giá như sau: $$\text{Tổng Giá Trị} = \text{Giá cơ bản của vật phẩm} + \sum \text{Giá trị sách Enchant tương ứng}$$ *Ví dụ:* Nếu `DIAMOND_SWORD` có giá `100.0` và `ENCHANTED_BOOK_SHARPNESS_5` có giá `1500.0`, thì thanh kiếm Kim cương sắc bén 5 khi bán sẽ có giá là **1600.0**.

#### 2.4. Định giá thuốc nước

Định giá theo các loại hiệu ứng thuốc bằng định dạng: `<TÊN_MATERIAL_POTION>_<TÊN_HIỆU_ỨNG_CHỮ_HOA>`.

```yaml
prices:
  POTION_FIRE_RESISTANCE: 40.0
  LINGERING_POTION_STRONG_STRENGTH: 97.5
  SPLASH_POTION_HEALING: 45.0
```

#### 2.5. Định giá pháo hoa

Định giá pháo hoa dựa trên thời gian bay (flight duration power) của chúng:

```yaml
prices:
  FIREWORK_ROCKET_1: 1.0  # Pháo hoa cấp độ bay 1
  FIREWORK_ROCKET_2: 2.0  # Pháo hoa cấp độ bay 2
  FIREWORK_ROCKET_3: 3.0  # Pháo hoa cấp độ bay 3
```

#### 2.6. Định giá Ominous Bottle

Hỗ trợ định giá chai điềm xấu theo cấp độ hiệu ứng từ 1 đến 5:

```yaml
prices:
  OMINOUS_BOTTLE_1: 50.0   # Điềm xấu I
  OMINOUS_BOTTLE_5: 250.0  # Điềm xấu V
```

#### 2.7. Chặn định giá và bán vật phẩm custom qua NBT

Để tránh việc người chơi bán các vật phẩm custom đắt tiền từ các plugin khác (như MMOItems, ItemsAdder, Oraxen, ecoitems, Nexo) với giá trị của vật liệu thô cơ bản, bạn có thể thiết lập chặn trong `config.yml`:

```yaml
# Các key NBT của item custom được hỗ trợ chặn bán
custom_item_nbt_keys:
  - "ecoitems:id"
  - "oraxen_id"
  - "itemsadder_id"
  - "mmoitems_type"
  - "nexo_id"
```

{% hint style="warning" %}
Bất kỳ vật phẩm nào chứa ít nhất một key NBT ở trên sẽ bị bỏ qua và được định giá **0** khi bán. Cách này giúp tránh phá vỡ kinh tế máy chủ.
{% endhint %}

***

### 3. Danh mục bán hàng và tiến trình (`sell/*.yml`)

Hệ thống cho phép chia nhỏ vật phẩm ra thành các danh mục riêng (ví dụ: `ores.yml`, `crops.yml`...). Mỗi danh mục được định nghĩa trong một file YAML riêng biệt đặt tại thư mục `plugins/SolarWorth/sell/`.

#### 3.1. Cấu trúc cấu hình danh mục

* `slot`: Vị trí nút của danh mục này trong giao diện GUI bán hàng chính (`/sell`).
* `material`: Icon của nút danh mục.
* `title` & `lore`: Tên hiển thị và mô tả của danh mục.

#### 3.2. Cấu hình tiến trình nâng cấp Multiplier (`progress`)

Cho phép người chơi nhận thêm hệ số nhân giá bán (Multiplier) khi đạt được các mốc tổng doanh thu bán hàng tích lũy trong danh mục đó:

* `layout`: Bản đồ giao diện GUI nâng cấp (mạng lưới 9x6) sử dụng các ký tự đặc biệt:
  * `-`: Đại diện cho kính xám lấp đầy ô trống.
  * `c`: Vị trí đặt icon thông tin danh mục.
  * `b`: Nút quay lại.
  * `(N)`: Vị trí hiển thị mốc cấp độ nâng cấp thứ $N$.
* `requirements`: Định nghĩa các cấp độ nâng cấp:

  ```yaml
  requirements:
    '1':
      multiplier: 1.1   # Hệ số nhân bán hàng mới
      price: 25000      # Tổng tiền tích lũy cần bán được trong danh mục để đạt mốc
    '2':
      multiplier: 1.2
      price: 150000
  ```
* `items`: Thiết kế các loại ô trong GUI tiến trình tương ứng với trạng thái của người chơi:
  * `filler`: Kính trang trí.
  * `p.current`: Cấp độ đang thực hiện.
  * `p.complete`: Cấp độ đã hoàn thành (đã nhận multiplier).
  * `p.incomplete`: Cấp độ chưa mở khóa.

#### 3.3. Catalogue vật phẩm của danh mục (`catalog`)

Cấu hình danh sách các vật phẩm thuộc về danh mục này để hiển thị khi người chơi click vào nút danh mục. Danh sách vật phẩm được định nghĩa tại `catalog.items.list`:

```yaml
catalog:
  items:
    lore:
      - "&fGiá: #00F986${price}"
    list:
      - COAL_ORE
      - IRON_INGOT
      - GOLD_INGOT
      - DIAMOND
```

{% hint style="info" %}
Bạn có thể dùng wildcard như `*potion` hoặc `*enchanted_book` để tự động thêm toàn bộ thuốc hoặc sách phù phép vào danh mục mà không cần liệt kê từng ID.
{% endhint %}

***

### 4. Công cụ bán hàng và chống dupe

Cấu hình các loại công cụ bán hàng tự động trong file `selltool.yml`. SolarWorth cung cấp **2 công cụ mặc định** và hệ thống **Custom Tools** cho phép tạo không giới hạn loại công cụ.

#### 4.1. Công cụ mặc định

Hai công cụ sẵn có không cần cấu hình thêm:

**Sell Axe**

Click chuột phải vào rương/thùng chứa để bán **toàn bộ** nội dung bên trong.

```yaml
sell-axe:
  display-name: "#A303F9ᴀᴍᴇᴛʜʏsᴛ sᴇʟʟ ᴀxᴇ"
  material: NETHERITE_AXE
  model: -1                  # Custom Model Data (-1 = không dùng)
  mode: duration             # "duration" (hết hạn theo thời gian) hoặc "uses" (theo số lần dùng)
  duration: 3600             # Thời gian sử dụng (giây)
  uses: 50                   # Số lần dùng (chỉ khi mode: uses)
  allow-enchanted-books: true
  enchants:
    - "EFFICIENCY:5"
    - "UNBREAKING:3"
    - "MENDING"
  container-filter:
    mode: blacklist           # blacklist hoặc whitelist
    list:
      - ENDER_CHEST
```

**Sell Stick**

Click chuột phải để bán tất cả rương/shulker trong **bán kính** gần người chơi.

```yaml
sell-stick:
  display-name: "#A303F9ᴀᴍᴇᴛʜʏsᴛ sᴇʟʟ sᴛɪᴄᴋ"
  material: STICK
  model: -1
  radius: 20                 # Bán kính quét (blocks, tối đa 32)
  mode: uses
  duration: 3600
  uses: 10
  allow-enchanted-books: true
  enchants:
    - "UNBREAKING:3"
    - "MENDING"
  container-filter:
    mode: blacklist
    list:
      - ENDER_CHEST
```

**Thuộc tính chung cho cả 2 công cụ mặc định:**

| Thuộc tính              | Mô tả                                                                      |
| ----------------------- | -------------------------------------------------------------------------- |
| `display-name`          | Tên hiển thị (hỗ trợ HEX color `#RRGGBB`)                                  |
| `lore`                  | Mô tả item (hỗ trợ `§` color code và placeholder `{radius}`)               |
| `material`              | Loại vật liệu Minecraft                                                    |
| `model`                 | Custom Model Data cho resource pack (`-1` = không dùng)                    |
| `mode`                  | Chế độ hết hạn: `duration` (theo thời gian) hoặc `uses` (theo số lần dùng) |
| `duration`              | Thời gian sử dụng tính bằng giây (chỉ áp dụng khi `mode: duration`)        |
| `uses`                  | Số lần sử dụng tối đa (chỉ áp dụng khi `mode: uses`)                       |
| `allow-enchanted-books` | Cho phép bán Enchanted Book hay không                                      |
| `enchants`              | Danh sách enchant gắn lên item (định dạng `ENCHANT_NAME:level`)            |
| `container-filter`      | Bộ lọc loại rương — `blacklist` hoặc `whitelist`                           |

#### 4.2. Công cụ tùy chỉnh

Bạn có thể tự tạo **không giới hạn** số lượng công cụ bán hàng trong mục `custom-tools` bằng cách gán cho chúng một trong **8 loại hành động** sau:

| Loại Hành Động (Action) | Mô tả chi tiết                                                               | Cấu hình liên quan                                          |
| ----------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `AUTO_SELL_MINE`        | Tự động bán quặng đào được khi sử dụng cúp này để khai thác.                 | `radius` (0 = 1 block, 1 = 3x3x3, 2 = 5x5x5)                |
| `AUTO_HARVEST_SELL`     | Click chuột phải vào cây trồng đã chín để tự động thu hoạch và bán nông sản. |                                                             |
| `AUTO_SELL_PICKUP`      | Tự động hút vật phẩm rơi xung quanh và bán trực tiếp ngay khi nhặt được.     | `radius` (Bán kính hút vật phẩm; 0 = theo sự kiện mặc định) |
| `AUTO_SELL_KILL`        | Tiêu diệt quái vật sẽ tự động thu gom vật phẩm rơi ra từ quái và bán.        |                                                             |
| `AUTO_SELL_FISH`        | Tự động bán cá và báu vật câu được ngay khi câu thành công.                  |                                                             |
| `SELL_CONTAINER`        | Click chuột phải vào một rương/thùng chứa để bán toàn bộ vật phẩm bên trong. | `container-filter` (Blacklist/Whitelist rương)              |
| `SELL_RADIUS`           | Click chuột phải để quét và bán tất cả rương chứa đồ xung quanh người chơi.  | `radius` (Bán kính quét rương)                              |
| `SELL_INVENTORY`        | Click chuột phải để bán toàn bộ túi đồ cá nhân (bao gồm Shulker Box).        | Tự động bỏ qua công cụ bán hàng đang cầm                    |

**Ví dụ cấu hình Custom Tool:**

```yaml
custom-tools:
  # Key bên dưới chính là custom_id dùng trong lệnh /selltool give
  auto-sell-pickaxe:
    display-name: "#00F986ᴀᴜᴛᴏ-sᴇʟʟ ᴘɪᴄᴋᴀxᴇ"
    lore:
      - "§7Tự động bán tất cả quặng đào được"
    material: NETHERITE_PICKAXE
    model: -1
    action: AUTO_SELL_MINE       # Bắt buộc: 1 trong 8 loại hành động
    radius: 1                    # Bán kính đào: 0=1block, 1=3x3, 2=5x5
    mode: uses
    uses: 100
    duration: 3600
    enchants:
      - "EFFICIENCY:5"
      - "UNBREAKING:3"

  magnet-bag:
    display-name: "#00F7FBᴍᴀɢɴᴇᴛ sᴇʟʟ ʙᴀɢ"
    lore:
      - "§7Tự động hút và bán vật phẩm khi nhặt được"
      - "§7Bán kính hút: §f5 blocks"
    material: CHEST
    model: -1
    action: AUTO_SELL_PICKUP
    radius: 5                    # Bán kính hút vật phẩm từ xa
    mode: duration
    duration: 7200
    enchants:
      - "UNBREAKING:3"
```

#### 4.3. Lệnh give công cụ

```
/selltool give axe <player> [time/uses]       → Cấp Sell Axe
/selltool give stick <player> [time/uses]     → Cấp Sell Stick
/selltool give <custom_id> <player> [time/uses] → Cấp Custom Tool
```

**Ví dụ:**

* `/selltool give axe Steve 1h30m` — Give Sell Axe cho Steve với thời hạn 1 giờ 30 phút
* `/selltool give auto-sell-pickaxe Steve 200` — Give custom tool `auto-sell-pickaxe` cho Steve với 200 lần dùng
* `/selltool give magnet-bag Steve` — Give Magnet Bag với thời gian/lượt mặc định từ config

{% hint style="info" %}
Tham số `[time/uses]` là tùy chọn. Nếu không chỉ định, plugin dùng giá trị mặc định từ `selltool.yml`. Định dạng thời gian hỗ trợ gồm `30s`, `5m`, `1h`, `1h30m` và `2d12h`.
{% endhint %}

#### 4.4. Cơ chế chống dupe lore ảo

Cả hai phiên bản Standard và NMS đều tích hợp bộ lọc gói tin thông minh:

* **Slot Filtering**: Chặn hoàn toàn việc chèn lore định giá vào kho chế tạo đồ cá nhân của người chơi (Slot 1-4) hoặc khi chế tạo bằng bàn chế tạo (Crafting Table).
* **Inventory Whitelist**: Lore chỉ được chèn vào các rương chứa thông thường (Chest, Shulker, Barrel, Hopper, Player Inventory) và tự động lọc bỏ khi người chơi tương tác với các bàn chức năng đặc biệt như Anvil, Grindstone, Villager Trade, Beacon, v.v. Điều này giúp loại bỏ triệt để 100% lỗi dupe ảo hoặc lỗi hiển thị desync giá trị vật phẩm.

***

### 5. Các tính năng mở rộng tích hợp

#### 5.1. Đồng bộ giá sang SmartSpawner (`smartspawner-sync`)

SolarWorth hỗ trợ tự động đồng bộ giá vật phẩm sang hệ thống SmartSpawner để quản lý kinh tế tập trung. Cấu hình tại `config.yml`:

```yaml
smartspawner-sync:
  enabled: true
  file-path: "plugins/SmartSpawner/item_prices.yml"
  auto-reload: true
  reload-command: "smartspawner reload"
```

Hệ thống sẽ chỉ đồng bộ những vật phẩm thực sự được SmartSpawner sử dụng (quét từ `spawners_settings.yml`, `item_spawners_settings.yml`, `mob_drops.yml`) để giảm dung lượng file đồng bộ và tăng tốc độ xử lý.

#### 5.2. Discord Webhook cập nhật bảng giá (`webhook.yml`)

Gửi thông báo tự động lên Discord của Ban Quản Trị khi bảng giá vật phẩm có sự thay đổi (Thêm, sửa, hoặc xóa giá vật phẩm):

* **Batching Delay**: Gộp nhiều thay đổi giá trị và gửi định kỳ sau mỗi $X$ giây (mặc định 15s) giúp tránh bị Discord khóa (rate-limited) khi cập nhật hàng loạt giá trị.
* **Discord Embed / Plain Text**: Hỗ trợ hiển thị dạng khối Embed có màu sắc chuyên nghiệp hoặc plain text bao bọc trong code block định dạng `diff` (cho màu đỏ `-` và xanh lá `+` trực quan).

***

### 6. Tiền tệ tùy chỉnh (Custom Currency API)

SolarWorth cho phép tích hợp bất kỳ loại tiền tệ nào khác thông qua API.

#### Cấu hình trong `config.yml`

```yaml
# Sử dụng cú pháp CUSTOM:<Tên loại tiền tệ>
default_currency: "CUSTOM:Ruby"
```

#### Cách đăng ký qua Java code

1. Thực thi cài đặt Interface `CustomCurrencyHandler`:

```java
import org.bukkit.entity.Player;
import org.omhvn.solarworth.api.CustomCurrencyHandler;

public class MyCustomCurrency implements CustomCurrencyHandler {
    @Override
    public String getName() {
        return "Ruby"; // Tên trùng khớp với config (không phân biệt hoa thường)
    }

    @Override
    public void reward(Player player, double amount) {
        // Thực hiện cộng tiền cho người chơi tại đây
        System.out.println("Cộng " + amount + " Ruby cho " + player.getName());
    }
}
```

2. Đăng ký Handler của bạn vào API của SolarWorth khi khởi động plugin của bạn:

```java
import org.omhvn.solarworth.api.SolarWorthAPI;

// Đăng ký
SolarWorthAPI.get().registerCustomCurrency(new MyCustomCurrency());

// Hủy đăng ký khi tắt plugin của bạn
SolarWorthAPI.get().unregisterCustomCurrency("Ruby");
```