Catcher — nhập liệu trong menu

Catcher (action catcher:, alias input-catcher) cho phép menu hỏi người chơi nhập chữ/số — qua chat, sign, anvil hoặc book — rồi dùng giá trị đó làm biến. Fork này bổ sung validation regex từng stage. Đây là nền tảng của các menu shop (nhập số lượng), tìm kiếm, đặt tên, chuyển khoản…

Cấu trúc#2>

actions:
  all:
    - catcher:
        price:                    # ID của catcher stage (tự đặt)
          type: SIGN              # CHAT | SIGN | ANVIL | BOOK
          display: '&bNhập giá'   # tiêu đề hiển thị
          validation: '^[1-9][0-9]*$'   # (fork) regex full-match
          start:                  # reaction chạy khi mở catcher
            - 'actionbar: &b&lHãy nhập một số'
          fail:                   # (fork) reaction khi validation từ chối
            - 'tell: &cSai định dạng! Thử lại.'
            - 'retype'            # hỏi lại stage này
          cancel:                 # reaction khi hủy
            - 'tell: &8Đã hủy nhập'
          end:                    # reaction khi nhập xong
            - 'set-args: {0} `${js: Math.min(Math.max(varInt("{meta:input}"), 1), 64)}`'
            - 'open: Shop-Handler-Purchase'

Validation — kiểm tra input (fork)#2>

• validation: (alias valid, pattern, regex) là regex full-match compile một lần lúc load menu — không hỗ trợ placeholder trong pattern.
• Input bị từ chối → không lưu meta, end: không chạy. Reaction fail: (alias invalid, reject) chạy thay thế — dùng để phản hồi.
• Luồng fail: kết thúc fail bằng action retype để hỏi lại đúng stage đó. Không có retype → chuỗi catcher kết thúc sau fail.
• Từ hủy (settings.yml Action.Inputer.Cancel-Words) ưu tiên hơn validation — cancel không cần khớp regex vẫn hủy được.
• Regex sai được cảnh báo lúc load và tắt validation cho stage đó (menu vẫn nạp, không crash).
• {meta:input} giữ input stage cuối; {meta:input-<stage-id>} giữ từng stage riêng — ví dụ {meta:input-target}, {meta:input-money}.

4 loại input#2>

Type	Cách nhập	Ghi chú
CHAT	Gõ vào chat (plugin chặn tin nhắn đó)	Mặc định khi type sai/không khai báo. Người chơi gõ từ hủy để thoát.
SIGN	Gõ lên sign ảo	Packet-based, hỗ trợ Bedrock (Geyser). Có thể gõ 4 dòng.
ANVIL	Đặt tên item trong anvil ảo	Thao tác tự nhiên nhất trên Java. Đóng anvil = hủy (ANVIL_CANCEL).
BOOK	Viết vào book ảo rồi ký	Nhập được nhiều dòng.

Biến kết quả#2>

Sau khi nhập xong, nội dung nằm trong meta input:

Biến	Giá trị
{meta:input} / %shinnui_meta_input%	Chuỗi người chơi nhập lần cuối
{meta:input-<stage>}	Nội dung của stage cụ thể (giữ nguyên sau các stage sau)

Vì là chuỗi thô, hãy kiểm tra/ép kiểu trước khi dùng:

// Ép về số, giới hạn 1-64
js: Math.min(Math.max(varInt("{meta:input}"), 1), 64)

// Kiểm tra là số
js: utils.isNumber("{meta:input}")

Từ khóa hủy#2>

Với CHAT catcher, người chơi hủy bằng cách gõ một từ khớp regex trong Action.Inputer.Cancel-Words (settings.yml):

Action:
  Inputer:
    Cancel-Words:
      - 'cancel|quit|end'
      - 'q'

Mặc định: cancel, quit, end, q (không phân biệt hoa thường).

Ví dụ hoàn chỉnh — chuyển khoản 2 stage có validation#2>

actions:
  all:
    - catcher:
        target:
          type: CHAT
          validation: '^[A-Za-z0-9_]{3,16}$'
          start: 'tell: &3Nhập tên người nhận (3-16 ký tự):'
          fail:
            - 'tell: &cTên không hợp lệ (chữ/số/_, 3-16 ký tự).'
            - 'retype'
          cancel: 'tell: &7Đã huỷ giao dịch.'
          end: 'tell: &7Người nhận: &f{meta:input-target}'
        money:
          type: CHAT
          validation: '^[1-9][0-9]*$'
          start: 'tell: &3Nhập số tiền:'
          fail:
            - 'tell: &cSố tiền phải là số nguyên dương.'
            - 'retype'
          cancel: 'tell: &7Đã huỷ giao dịch.'
          end:
            - condition: 'js: utils.isPlayerOnline(vars("{meta:input-target}"))'
              actions:
                - 'tell: &aGửi &f{meta:input-money} &acho &f{meta:input-target}&a!'
              deny:
                - 'tell: &cNgười chơi &f{meta:input-target} &ckhông online.'
                - 'return'

Đang mở menu khi catcher chạy — GUI sẽ được thay bằng sign/anvil/book, sau khi xong menu vẫn giữ nguyên trạng thái (icon, trang, tham số). Muốn "hỏi lại" từ đầu, dùng action retype để chạy lại catcher cuối cùng.

Cần người chơi nộp đồ thay vì nhập chữ? Đó là Input Menu (kéo vật phẩm vào GUI) — tính năng riêng của fork này.