HƯỚNG DẪN CowQuest
==================

CẤU TRÚC THƯ MỤC (plugins/CowQuest/)
  config.yml      cài đặt chung (kiểu chữ, nhận nhiệm vụ, kinh tế, tiền tệ, bảng xếp hạng)
  messages.yml    mọi tin nhắn
  commands.yml    TÙY CHỈNH LỆNH mở nhiệm vụ / menu
  gui.yml         giao diện rương của menu nhiệm vụ (người chơi Java)
  forms.yml       FORM PE: chữ, icon nút cho người chơi Bedrock
  quests/*.yml    mỗi nhóm nhiệm vụ 1 file (tên file = ID nhóm)
  menus/*.yml     menu tùy chỉnh kiểu DeluxeMenus (tên file = id menu)
  data.yml        tiến độ người chơi        balances.yml  số dư (kinh tế riêng)
Sau khi sửa file, gõ /cowquest reload.
Nếu server còn thư mục plugins/CowQuest-Premium, lần chạy đầu plugin tự chép dữ liệu sang plugins/CowQuest.

TỰ RESET NHIỆM VỤ (config.yml -> auto-reset)
  Khi người chơi hoàn thành TẤT CẢ nhiệm vụ, sau "delay" (mặc định 1d = 1 ngày, tính giờ thật kể cả lúc offline)
  tiến độ nhiệm vụ của họ được đặt về ban đầu. Bật/tắt: enabled. Chỉ tính vài nhóm: categories: [tieuphu, thosan].
  Có thể chạy lệnh khi hoàn thành / khi reset (on-complete-commands, commands, biến %player%).
  Hiển thị: biến %cowquest_reset_in%, %cowquest_reset_seconds%, %cowquest_resets%, %cowquest_all_complete%;
  menu chính (rương) có đồng hồ đếm ngược ở main.reset-info trong gui.yml; form PE hiện ở phần mô tả.

TÙY CHỈNH GUI NHIỆM VỤ (gui.yml + từng file quests/<nhóm>.yml)
  gui.yml:   main.rows / category.rows (1-6 hàng), main.sort (order|name|progress|progress-asc),
             main.hide-locked, main.hide-maxed, main.reset-info, mọi vật phẩm (material, name, lore, glow...), text.*
  quests/<nhóm>.yml mục gui: (xem quests/vidu.yml): slot riêng ở menu chính, hide, title, main-item, info,
             level-completed / level-current / level-locked, level-slots, fill, accent, buttons.
  config.yml: sounds.* (âm thanh), progress.action-bar(-format), level-complete.title.* (tiêu đề lớn khi xong cấp).

FORM PE (người chơi Bedrock / Geyser + Floodgate)
  Cần plugin Floodgate. Người chơi PE nhận form có icon ở từng nút thay cho giao diện rương; người chơi Java không đổi.
  Không có Floodgate thì mọi người dùng giao diện rương như cũ. Kiểm tra bằng /cowquest form.
  forms.yml:  enabled | quest-forms | menu-forms   bật/tắt từng phần
              icons.auto: curated (mặc định: chỉ icon chắc chắn có) | path (đoán theo tên, dễ bị ô tím-đen) | url | none
              icons.overrides: ép icon riêng theo vật liệu
              quest.*: chữ của form nhiệm vụ; quest.icons.*: icon các nút chức năng
  Icon ghi dạng:  path:textures/items/diamond   |   url:https://...   |   DIAMOND (theo vật liệu)   |   none
  Nhóm nhiệm vụ: thêm  form-icon: "path:textures/items/..."  vào file quests/<nhóm>.yml (trống = theo icon của nhóm).
  Màu hex tự đổi sang màu gần nhất (Bedrock chỉ có 16 màu chữ).

MENU TÙY CHỈNH (menus/*.yml)  tương thích cú pháp DeluxeMenus
  Copy menu DeluxeMenus vào thư mục menus/ rồi /cowquest menu reload. Mở: /cowquest menu open <id> [người] [tham số].
  Menu: menu_title, open_command (chuỗi hoặc danh sách), register_command: true (mới tạo lệnh), size, inventory_type
        (CHEST HOPPER DROPPER DISPENSER), args, arg_requirements, open_requirement, open_commands, close_commands, update_interval (giây).
  Item: material, slot / slots (vd [0-8, 10]), priority (số nhỏ ưu tiên), update, view_requirement, display_name, lore, amount,
        dynamic_amount, data, enchantments ["sharpness;3"], item_flags, hide_attributes/enchantments/effects/unbreakable,
        unbreakable, glow, custom_model_data, rgb, potion_effects ["SPEED;600;1"],
        click_commands, left_/right_/shift_left_/shift_right_/middle_click_commands, click_requirement và <loại>_click_requirement.
  material: tên vật liệu | head-<tên> | basehead-<base64> | texture-<hash> | water_bottle | main_hand | off_hand | armor_helmet...
  Điều kiện (type): has permission, has money (currency:), has exp, has item, string equals / equals ignorecase / contains / length,
        regex matches, javascript, is near, is object, == != > >= < <=, kèm tiền tố ! để phủ định.
        optional, minimum_requirements, stop_at_success, deny_commands, success_commands.
        "javascript" dùng bộ tính biểu thức riêng (số, chữ, so sánh, && || !, + - * / %), KHÔNG chạy JavaScript đầy đủ.
  Hành động: [player] [console] [commandevent] [op] [chat] [message] [broadcast] [minimessage] [broadcastminimessage]
        [json] [broadcastjson] [openguimenu] <menu> [tham số] [close] [refresh] [connect] <server> [takemoney] [givemoney]
        [takeexp] [giveexp] [takepermission] [givepermission] [sound] [broadcastsound] [broadcastsoundworld] [stopsound]
        Thêm: [actionbar] [title] tiêu đề;phụ đề, [quests] [nhóm].  Hậu tố: <delay=ticks> <chance=%>.
  Biến: %arg_<tên>%, {tên}, %player_name% %player_world% %player_level%..., %cowquest_...%, và mọi biến PlaceholderAPI.
  Chưa hỗ trợ (sẽ báo cảnh báo trong log): nbt_*, banner_meta, open_with_item, [meta], hdb-/itemsadder-/oraxen- material.

  Form PE cho menu tùy chỉnh (tự động, không cần sửa menu cũ):
    - Mỗi vật phẩm đang hiện (qua view_requirement) và CÓ hành động click thành 1 nút; vật phẩm trang trí (kính nền...) bị bỏ.
    - Chữ nút = display_name, icon = theo material. Bedrock chỉ có 1 kiểu bấm: dùng left_click_commands, nếu không có thì
      click_commands, rồi tới các kiểu click khác.
    - Tùy chỉnh thêm:
        form:                         (mức menu)
          enabled: true               false = người chơi PE vẫn thấy giao diện rương
          title: "..."                trống = menu_title
          content: ["...", "..."]     chữ phía trên các nút
          lore_lines: 0               số dòng lore ghép dưới tên nút
        form:                         (mức vật phẩm)
          show: true|false            ép hiện / ẩn nút
          text: "Tên\nDòng phụ"       chữ nút
          icon: "path:..." | "url:..." | DIAMOND | none
          order: 1                    thứ tự nút (mặc định theo slot)
    - close_commands chạy khi người chơi PE đóng form (bấm X); không chạy sau khi bấm nút.
    - [refresh] và update_interval không có tác dụng với form.

LỆNH TÙY CHỈNH (commands.yml)
  Mỗi mục = 1 lệnh: tên, aliases, action, permission, description, enabled.
  action: quest | quest:<nhóm> | top | menu | menu:<id>
  Ví dụ lệnh mở thẳng nhóm Tiều Phu bằng /tieuphu:   tieuphu: { action: "quest:tieuphu" }
  override-existing: true để ghi đè lệnh trùng tên của plugin khác.
  Lệnh gốc /cowquest (alias /cq) luôn có sẵn.

PLACEHOLDERAPI
  %cowquest_top_1_name% %cowquest_top_1_value%  (hạng 1 tổng)
  %cowquest_top_tieuphu_1_name% %cowquest_top_tieuphu_1_value%  (hạng 1 của nhóm)
  %cowquest_total% %cowquest_rank% %cowquest_active% %cowquest_balance% %cowquest_balance_formatted%
  %cowquest_level_<nhóm>% %cowquest_done_<nhóm>% %cowquest_percent_<nhóm>%

LỆNH & QUYỀN
  /nv (hoặc /nhiemvu, /quest)   menu nhiệm vụ        /nv nhan|huy <nhóm>   /nv top [nhóm]
  /cowquest help   danh sách lệnh   /cowquest menu ...   /cowquest form (admin)
  Quyền: cowquest.use (mặc định ai cũng có), cowquest.admin (op)

KHẮC PHỤC
  - Lệnh bị plugin khác chiếm: dùng /cowquest:<lệnh> hoặc override-existing: true trong commands.yml.
  - Menu không mở: xem log khi /cowquest menu reload (cảnh báo bắt đầu bằng [menu]).
  - Người chơi PE không thấy form: cài Floodgate, kiểm tra /cowquest form; xem log có dòng [form].
  - Icon nút PE trống: texture path không tồn tại trong Bedrock -> ghi icon riêng (url: hoặc path:) hoặc thêm vào icons.overrides.
  - Tiền PlayerPoints không hoạt động: cần plugin PlayerPoints bật; currency type phải là points.
