> 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/gioi-thieu.md).

# Giới thiệu

## ☀️ SolarDuels Plugin Wiki

Chào mừng bạn đến với tài liệu chính thức của **SolarDuels**.

SolarDuels là giải pháp duel PvP 1v1 toàn diện cho máy chủ Minecraft hiện đại.

### Giới thiệu plugin

SolarDuels tập trung vào trải nghiệm mượt, công bằng và giàu tính năng.

Plugin hỗ trợ hồi phục arena bằng schematic, matchmaking, ELO, spectator và Folia.

SolarDuels phù hợp cho SkyWars, Factions, Survival, KitPvP và các máy chủ cần đấu trường 1v1.

### Chức năng nổi bật

* **Auto-Regen Arena** — khôi phục map bằng schematic bất đồng bộ sau trận đấu.
* **Casual Queue** — hàng chờ tự ghép cặp qua GUI hoặc lệnh.
* **Rank và ELO** — tính điểm thắng thua và tự đổi tier theo `ranks.yml`.
* **Spectator Mode** — cho người khác xem trận đấu mà không gây ảnh hưởng.
* **Floodgate/Geyser** — tự nhận diện người chơi Bedrock để tối ưu hiển thị.
* **Folia-ready** — tương thích scheduler vùng và scheduler toàn cục của Folia.
* **Arena Protection** — chặn block bị cấm và dọn block người chơi đặt sau trận.
* **MiniMessage** — hỗ trợ gradient, HEX và định dạng Adventure hiện đại.
* **Matrix GUI Layout** — cấu hình GUI bằng bản đồ ký tự trực quan.
* **BossBar linh hoạt** — đổi tiêu đề, màu và kiểu hiển thị theo thời gian.
* **Entity-relative Sound** — âm thanh phát theo vị trí người chơi.
* **Queue ETA** — ước tính thời gian chờ dựa trên lịch sử ghép trận gần nhất.

### Matrix GUI Layout

SolarDuels hỗ trợ bố cục GUI dạng ma trận trong thư mục `gui/`.

Mỗi dòng trong `LAYOUT` tương ứng một hàng inventory.

```yaml
QUEUE-MENU:
  TITLE: "&8ǫᴜᴇᴜᴇ ᴄᴏɴꜰɪʀᴍ"
  LAYOUT:
    - "#########"
    - "c##wsr##d"
    - "#########"
  FILLER:
    ENABLED: true
    MATERIAL: GRAY_STAINED_GLASS_PANE
    NAME: " "
  BUTTONS:
    CANCEL:
      LAYOUT-CHAR: "c"
      MATERIAL: RED_STAINED_GLASS_PANE
      NAME: "&#FC0000ᴄᴀɴᴄᴇʟ"
      LORE:
        - "&fClick to leave queue"
      ACTION: CANCEL
```

#### Quy tắc quan trọng

* Mỗi dòng trong `LAYOUT` phải có đúng `9` ký tự.
* Ký tự `#` là ô trống và sẽ được `FILLER` phủ nếu bật.
* Mỗi nút có thể khai báo `LAYOUT-CHAR` để ánh xạ vào bản đồ.
* Nếu thiếu `LAYOUT-CHAR`, hệ thống dùng chữ cái đầu của tên nút.
* Nếu ký tự không xuất hiện trong `LAYOUT`, hệ thống fallback sang `SLOT`.
* Một ký tự có thể xuất hiện nhiều lần để tạo danh sách động.

{% hint style="warning" %}
Sai độ dài `LAYOUT` là lỗi cấu hình phổ biến nhất. Mỗi dòng luôn phải đủ `9` ký tự.
{% endhint %}

### BossBar tùy biến

BossBar thời gian trận đấu có thể tùy chỉnh trực tiếp trong `config.yml`.

```yaml
BOSSBAR:
  ENABLED: true
  TITLE: "<gray>⏱ <white>{time} <gray>còn lại"
  OVERLAY: "PROGRESS"
  TIME-FORMAT: "human"
  COLORS:
    - "GREEN:60"
    - "YELLOW:20"
    - "RED:0"
```

Hệ thống duyệt `COLORS` từ trên xuống dưới.

Mốc đầu tiên khớp với thời gian còn lại sẽ được áp dụng.

Ví dụ, còn `35` giây sẽ dùng `YELLOW:20`.

### Cấu trúc thư mục plugin

```
plugins/SolarDuels/
├── config.yml
├── messages.yml
├── ranks.yml
├── gui/
│   ├── queue.yml
│   ├── duel.yml
│   ├── select_region.yml
│   └── accept.yml
├── data/
│   ├── solar_duels.db
│   ├── arenas.yml
│   ├── playerdata/
│   └── schematics/
```

{% hint style="info" %}
Toàn bộ dữ liệu động được tách vào thư mục `data/` để thư mục gốc luôn gọn.
{% endhint %}

### Yêu cầu và phiên bản

* **Minecraft:** `1.21.x`
* **Khuyên dùng:** **Paper 1.21.1+**
* **API target:** `1.21`
* **Folia:** hỗ trợ đầy đủ
* **Soft depend:** `PlaceholderAPI`

#### Thư viện tích hợp sẵn

* `HikariCP 5.1.0` — kết nối cơ sở dữ liệu hiệu năng cao.
* `sqlite-jdbc 3.45.1.0` — lưu trữ cục bộ bằng SQLite.
* `mysql-connector-j 8.3.0` — kết nối MySQL từ xa.

### Tích hợp SolarElo

SolarDuels có thể đồng bộ ELO với SolarElo qua `USE-SOLARELO` trong `config.yml`.

Khi bật tích hợp:

* ELO hiển thị trên placeholder sẽ lấy từ SolarElo.
* Matchmaking sẽ dùng điểm ELO của SolarElo.
* Hệ thống rank sẽ dựa trên dữ liệu ELO đã đồng bộ.
* Kết quả trận đấu sẽ cập nhật ELO trực tiếp qua API.

### Điều hướng nhanh

* [Arena/Map](/solarplugins-docs/plugins/solarduels/arena-map.md)
* [Lệnh](/solarplugins-docs/plugins/solarduels/lenh.md)
* [PlaceholderAPI](/solarplugins-docs/plugins/solarduels/placeholderapi.md)
* [API Guide](/solarplugins-docs/plugins/solarduels/api-guide.md)
* [Quyền hạn](/solarplugins-docs/plugins/solarduels/quyen-han.md)
* [Cấu hình](/solarplugins-docs/plugins/solarduels/cau-hinh.md)