> 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/solarchat/cau-hinh.md).

# Cấu hình

#### File chính: `config.yml`

Quản lý chat chung, định dạng màu sắc, Anti-Spam, từ cấm và Hover hiển thị thống kê.

```yaml
# Ngôn ngữ hoạt động chính (vi: Tiếng Việt, en: Tiếng Anh)
language: "vi"

# Bật debug log
debug: false

chat:
  enabled: true
  # Định dạng chat mặc định (Sử dụng LuckPerms)
  format: "{prefix}{username-color}{name}#C8CFDC: {message-color}{message}"

# Định dạng riêng cho từng nhóm LuckPerms
group-formats:
  # admin:   "&c[Admin] {prefix}{name}&f: {message}"
  # default: "{prefix}{name}&7: &f{message}"

# Lưu trữ log tin nhắn chat vào thư mục logs
chat-logs:
  enabled: true

# Hệ thống chống spam chat
anti-spam:
  enabled: true
  # Giới hạn số lượng tin nhắn trong khoảng thời gian nhất định
  rate-limit:
    enabled: true
    max-messages: 5
    time-window: 10
    message: "#FC0000Bạn đang gửi tin nhắn quá nhanh! Vui lòng chờ một chút."
  # Cooldown giữa mỗi lần nhắn tin
  cooldown:
    enabled: true
    seconds: 3
    message: "#FC0000Vui lòng đợi {time} giây trước khi chat tiếp!"
  # Chặn tin nhắn giống nhau liên tiếp
  duplicate:
    enabled: true
    message: "#FC0000Không được gửi tin nhắn giống nhau liên tiếp!"

# Lọc từ ngữ thô tục / từ cấm
filtered-words:
  enabled: true
  words:
    - "dm"
    - "cl"
    - "vcl"
    - "đm"
  mode: "block" # block (không cho gửi) | censor (thay thế bằng kí tự ẩn)
  message: "#FC0000Tin nhắn của bạn chứa từ ngữ không phù hợp!"
  censor-char: "*"

# Hover Stats - Di chuột vào tên hiển thị thông tin
stats:
  enabled: true
  hover-enabled: true
  display:
    - "&7%luckperms_prefix%{player}"
    - "&7&m                 "
    - "#00FC00&l$ &fTiền #00FC00%nf_###E0X_vault_eco_balance%"
    - "#FC0000🗡 &fGiết người #FC0000%nf_###E0X_statistic_player_kills%"
    - "#FCE300⌚ &fThời gian chơi #FCE300%statistic_time_played%"
    - "&7&m                 "
    - "&7Nhấn để xem thống kê"
```

***

#### Module Discord: `modules/discord.yml`

Quản lý liên kết Discord Bot, đồng bộ chat, các sự kiện Game và Account Linking.

```yaml
enabled: true

# Điền token của bot Discord tạo từ trang Discord Developer Portal
bot-token: "YOUR_BOT_TOKEN_HERE"

# ID của kênh Discord đồng bộ chat
channel-id: "YOUR_CHANNEL_ID_HERE"

# Link Webhook của kênh Discord để hiển thị skin người chơi làm avatar tin nhắn gửi sang Discord
webhook-url: "YOUR_WEBHOOK_URL_HERE"

# Định dạng tin nhắn trong Minecraft khi có chat từ Discord
discord-to-minecraft-format: "&8[&bDiscord&8] &f{username}#{tag}: &7{message}"

# Đồng bộ các sự kiện Minecraft -> Discord
sync:
  chat: true
  join: true
  quit: true
  death: true
  advancement: true
  server-start: true
  server-stop: true

formats:
  # Cấu hình tin nhắn dạng văn bản thường (nếu tắt Embed tương ứng bên dưới)
  join: "**{player} joined the game**"
  quit: "**{player} left the game**"
  death: "💀 **{death_message}**"
  advancement: "🏆 **{player} has made the advancement [{advancement}]**"
  server-start: "🟩 **Server has started**"
  server-stop: "🟥 **Server has stopped**"

  # Cấu hình tin nhắn dạng Embed (Giống DiscordSRV)
  join-embed:
    enabled: false
    title: ""
    description: "📥 **{player}** joined the game"
    color: 65280
    thumbnail: "{player_avatar}" # Sử dụng avatar skin người chơi
  quit-embed:
    enabled: false
    title: ""
    description: "📤 **{player}** left the game"
    color: 16711680
    thumbnail: "{player_avatar}"
  death-embed:
    enabled: false
    title: ""
    description: "💀 **{death_message}**"
    color: 10066329
    thumbnail: "{player_avatar}"
  advancement-embed:
    enabled: true
    title: "🏆 {player} đã đạt thành tựu [{advancement}]!"
    description: "{description}"
    color: 16750080
    thumbnail: "{advancement_icon}" # Hiển thị chính xác ảnh của thành tựu đó

# Tự động cập nhật chủ đề kênh (Channel Topic) theo số lượng online
channel-topic:
  enabled: true
  update-interval: 300 # Giây (khuyến nghị >= 300 để tránh bị giới hạn Discord rate-limits)
  text: "SolarMC | Online: {online}/{max} | Server status: Online"

# Hoạt động của Bot hiển thị trên Discord
bot-activity:
  enabled: true
  type: "PLAYING" # PLAYING, WATCHING, LISTENING, COMPETING
  text: "SolarMC | {online}/{max} players"
  update-interval: 30

# Cấu hình đồng bộ Chat
chat-sync:
  webhook-enabled: true # Bật Webhook để gửi tin nhắn kèm skin avatar
  webhook-format: "{message}"
  # Định dạng gửi qua Bot thường nếu không có Webhook (Tự động hiển thị rank của LuckPerms)
  bot-format: "**[{rank}] {player}**: {message}"
  embed:
    enabled: false
    title: ""
    description: "**{player}**: {message}"
    color: 65535
    thumbnail: "{player_avatar}"

# Hệ thống liên kết tài khoản
account-linking:
  enabled: true
  code-expiry: 300 # Mã có hiệu lực trong 5 phút
  
  # Cấu hình bật/tắt các lệnh Discord Slash Commands
  commands:
    link: true
    unlink: true
    profile: true
    stats: true
    
  messages:
    not-linked: "&cTài khoản của bạn chưa được liên kết với Discord. Dùng lệnh &e/discord link &cđể lấy mã xác thực!"
    already-linked: "&aTài khoản của bạn đã được liên kết với Discord ID: &e{discord_tag}&a."
    code-generated: "&aMã liên kết tài khoản Discord của bạn là: &e{code}&a. Hãy nhắn lệnh &e/link {code} &acho bot trên Discord!"
    unlink-success: "&aĐã hủy liên kết tài khoản Discord thành công."
    link-success: "&aTài khoản của bạn đã được liên kết thành công với người dùng Discord &e{discord_tag}&a!"
```

***

#### Các Module Khác:

**`modules/announcements.yml` (Thông báo tự động)**

```yaml
enabled: true
interval: 50 # Tần suất gửi (giây)
order: "sequential" # sequential (tuần tự) | random (ngẫu nhiên)
default-sound:
  enabled: true
  type: "ENTITY_EXPERIENCE_ORB_PICKUP"
  volume: 1.0
  pitch: 1.0
messages:
  - message: "&8[&bDISCORD&8] &fDùng /discord để tham gia Discord!"
    sound:
      enabled: true
      type: "ENTITY_EXPERIENCE_ORB_PICKUP"
      volume: 1.0
      pitch: 1.0
  - message: "&8[&eNHẮC NHỞ&8] &fHãy ứng xử văn minh trong kênh chat!"
```

**`modules/chatping.yml` (Nhắc tên)**

```yaml
enabled: true
ping-prefix: "@" # Tiền tố trước tên để kích hoạt ping
ping-style: "&6&l" # Định dạng màu sắc của tên được ping trong chat
admin-permission: "solarchat.ping.admin"
sound:
  enable-sound: true
  name: "BLOCK_NOTE_BLOCK_PLING"
  volume: 1.0
  pitch: 1.0
notifications:
  enable-chat: true
  enable-title: true
  enable-actionbar: true
anti-ping:
  enabled: true
  max-pings: 3
  window-seconds: 10
```

**`modules/msg.yml` (Nhắn tin riêng)**

```yaml
enabled: true
bypass-permission: "solarchat.msg.bypass"
socialspy-permission: "solarchat.socialspy"
sound:
  enabled: true
  name: "ENTITY_EXPERIENCE_ORB_PICKUP"
  volume: 1.0
  pitch: 1.5
```

**`modules/nightvision.yml` (Nhìn đêm)**

```yaml
enabled: true
amplifier: 0 # Cấp độ hiệu ứng (0 = Nhìn đêm I)
```

**`modules/report.yml` (Tố cáo)**

```yaml
enabled: true
cooldown: 60 # Thời gian chờ giữa mỗi lần tố cáo (giây)
staff-sound:
  enabled: true
  type: "BLOCK_NOTE_BLOCK_PLING"
  volume: 1.0
  pitch: 2.0
discord:
  enabled: true
  webhook-url: "YOUR_REPORT_WEBHOOK_URL_HERE"
  embed:
    enabled: true
    title: "📢 Báo cáo người chơi"
    color: 16750080
    timestamp: true
```

**`modules/killreward.yml` (Phần thưởng hạ gục & Chat tương tác)**

Module này cho phép tự động trao thưởng cho người chơi khi họ hạ gục đối thủ khác trong PvP và nhắn các từ khóa chúc mừng hoặc tương tác thể thao (như `gg`, `ez`). Từ khóa được gõ trong thời hạn kích hoạt sẽ được tô màu/in đậm trên chat chung của server.

Hệ thống tích hợp giới hạn tối đa số lần nhận thưởng mỗi 2 giờ và chặn cùng địa chỉ IP để chống các hành vi gian lận/farming bằng clone.

```yaml
enabled: true

# Thời gian giới hạn (giây) sau khi giết người chơi khác để nhắn từ khóa nhận thưởng
window-seconds: 15

# Giới hạn số lần nhận thưởng tối đa trong mỗi 2 giờ
limit-enabled: true
limit-amount: 5
limit-reached-message: "&8[&cKillReward&8] &cBạn đã đạt giới hạn nhận thưởng tối đa ({limit} lần mỗi 2 giờ)!"

# Ngăn chặn người chơi farm mạng bằng tài khoản clone (cùng địa chỉ IP)
prevent-same-ip: true
same-ip-message: "&8[&cKillReward&8] &cKhông thể nhận phần thưởng khi hạ gục tài khoản có cùng địa chỉ IP với bạn!"

# Danh sách từ khóa kích hoạt phần thưởng (không phân biệt chữ hoa/thường)
trigger-words:
  - "gg"
  - "gigi"
  - "good game"
  - "ez"

# Định dạng thay thế hiển thị trong chat cho từng từ khóa (tô màu và in đậm)
word-formats:
  gg: "&#FFD700&lGG&r"
  gigi: "&#FFD700&lGiGi&r"
  "good game": "&#FFD700&lGood Game&r"
  ez: "&#FF5555&lEZ&r"

# Các phần thưởng người chơi nhận được
rewards:
  # Thưởng tiền trực tiếp qua Vault Economy (nếu có)
  money:
    enabled: true
    amount: 100.0

  # Các lệnh thực thi từ Console hệ thống ({player} tự động thay thế bằng tên người chơi)
  commands:
    enabled: true
    list:
      - "give {player} iron_ingot 3"

  # Âm thanh phát khi nhận thưởng
  sound:
    enabled: true
    value: "ENTITY_PLAYER_LEVELUP"
    volume: 1.0
    pitch: 1.2

  # Hiển thị chữ trên thanh hành động (ActionBar) của người chơi
  actionbar:
    enabled: true
    text: "&aBạn nhận được phần thưởng vì đã cư xử đẹp!"

  # Gửi tin nhắn thông báo trong khung chat của người chơi
  message:
    enabled: true
    text: "&8[&aKillReward&8] &7Bạn nhận được &e100 coins &7và &e3 Sắt &7vì đã chat &e{word}&7!"
```

***

### 5. Hướng dẫn thiết lập & Cài đặt

1. **Cài đặt plugin**: Sao chép file `SolarChat.jar` vào thư mục `plugins/` của máy chủ.
2. **Khởi chạy máy chủ**: Để plugin tự tạo các file cấu hình mặc định.
3. **Tích hợp LuckPerms & PlaceholderAPI**: Hãy cài đặt thêm [LuckPerms](https://luckperms.net/) và [PlaceholderAPI](https://extendedclip.com/placeholderapi/) để kích hoạt đầy đủ các tính năng hiển thị Rank, Hover Stats, và đồng bộ tốt nhất.
4. **Cấu hình Discord Bot**:
   * Truy cập [Discord Developer Portal](https://discord.com/developers/applications).
   * Tạo ứng dụng mới (New Application), chọn mục **Bot** và tạo Bot. Bật mục **Message Content Intent** và **Guild Members Intent** tại phần **Privileged Gateway Intents**.
   * Lấy **Bot Token** và dán vào trường `bot-token` trong file `modules/discord.yml`.
   * Sao chép ID của kênh Chat Discord của bạn dán vào `channel-id`.
   * Tạo Webhook cho kênh chat đó trên Discord và sao chép liên kết dán vào `webhook-url` để kích hoạt đồng bộ avatar skin người chơi Minecraft sang Discord.
   * Mời Bot vào máy chủ Discord của bạn thông qua liên kết sinh từ tab **OAuth2** -> **URL Generator** (chọn scope: `bot` và `applications.commands`, phân quyền quản lý tin nhắn và xem kênh).
5. **Tải lại cấu hình**: Gõ `/solarchat reload` trong game hoặc bảng điều khiển để hệ thống nạp cấu hình mới.