# FREEEXILE DESIGN REQUEST: ProMotion Touch Joystick & Action Buttons HUD

## 1. THÔNG TIN YÊU CẦU (METADATA)

- **Mã Yêu Cầu (Request ID)**: `DRQ-20261001-CLI-TOUCH-CONTROLS-PROMOTION`
- **ID**: `DRQ-20261001-CLI-TOUCH-CONTROLS-PROMOTION`
- **Tên Yêu Cầu (Title)**: Bộ Nút Điều Khiển Cảm Ứng Cổ Võ Công Thái Học Mobile 120Hz (ProMotion Touch Joystick & Action Buttons HUD)
- **Phòng Ban Khởi Tạo (Requesting Dept)**: Client Engine (Lead Client Architect)
- **Department**: Client Engine
- **Tài Liệu Nguồn Căn Cứ (Source Document)**: [client/webapp/js/engine/input_handler.js](file:///c:/Projects/FreeExile/client/webapp/js/engine/input_handler.js) & [client/webapp/index.html](file:///c:/Projects/FreeExile/client/webapp/index.html)
- **Phân Loại Tài Nguyên (Asset Category)**: `UI`
- **Asset Type**: `UI`
- **Mức Độ Ưu Tiên (Priority)**: `HIGH`
- **Sub-Agent Tiếp Nhận Chỉ Định (Assigned Subagent)**: `mobile_ui_designer`
- **Đường Dẫn Mục Tiêu (Target Path)**: `client/webapp/assets/ui/hud/virtual_joystick_atlas.png`
- **Target Path**: `client/webapp/assets/ui/hud/virtual_joystick_atlas.png`
- **Kích Thước (Dimensions)**: `512x256` (Must be 2^n)
- **Dimensions**: `512x256` (Must be 2^n)
- **Ngân Sách Dung Lượng (Size Budget)**: `< 150KB`
- **Size Budget**: `< 150KB`
- **Yêu Cầu Normal Map (Normal Map Required)**: `NO`
- **Normal Map Required**: `NO`
- **Ngày Khởi Tạo (Created Date)**: `2026-10-01`
- **Hạn Định Mục Tiêu (Target SLA)**: `48h`

---

## 2. BỐI CẢNH NGHIỆP VỤ & CỐT TRUYỆN (CONTEXT & LORE)

### 2.1. Bối Cảnh Võ Học & Tính Năng
Để mang lại trải nghiệm điều khiển chiến đấu ARPG chuẩn xác, nhạy bén và đậm chất công thái học trên màn hình cảm ứng iPhone ProMotion 120Hz:
- **Cần Gạt Ảo (Analog Virtual Joystick)**: Vòng tròn đế đá hoa cương khắc viền bát quái kèm núm gạt trung tâm bằng kim loại có hiệu ứng gợn sóng khi chạm.
- **Cụm 4 Nút Chiêu Thức Võ Học (Skill Action Buttons)**: Nút xuất chiêu kích thước lớn với 3 trạng thái thị giác: Sẵn sàng (Phát quang theo màu ngũ hành của chiêu), Đang hồi chiêu (Mặt đồng hồ quét tối dần), Hết nội lực (Đổi màu xám phong ấn).
- **Nút Thân Pháp Né Đòn (Dodge Roll Button)**: Nút né chiêu Huyễn Ảnh Bộ với vệt sáng biểu thị thời gian miễn nhiễm sát thương (i-frame) tức thì.

### 2.2. Mục Tiêu Trải Nghiệm Người Dùng (UX Goal)
Thao tác phản xạ cực nhanh không bị trượt ngón tay, kích thước vùng chạm rộng rãi ($\ge 64\times 64\text{ pt}$ theo chuẩn công thái học Apple). Phản hồi thị giác tức thời 0ms khi chạm nhả.

---

## 3. THÔNG SỐ KỸ THUẬT CHI TIẾT (TECHNICAL SPECIFICATIONS)

| Tiêu Chí Kỹ Thuật | Yêu Cầu Chi Tiết |
| :--- | :--- |
| **Góc Nhìn (Projection)** | 2D Mobile Touch HUD Overlay |
| **Độ Phân Giải (Resolution)** | `512x256` (Atlas gồm cần gạt và các nút bấm `128x128` - Chuẩn $2^n$) |
| **Định Dạng Tệp (File Format)** | `.png` (RGBA 32-bit lossless), `.webp` |
| **Kênh Màu & PBR Mapping** | Albedo (RGBA 32-bit) tương phản cao, tách kênh trạng thái Normal/Pressed/Disabled |
| **Tần Số Quét & Khung Hình** | 120 FPS ProMotion ($8.33\text{ ms/frame}$), zero latency cảm ứng |
| **Bảng Màu & Hệ Ngũ Hành** | Đen sắt cổ, viền đồng thau, điểm xuyết ánh sáng nội lực ngũ hành |
| **Giao Diện Di Động (Safe Area)** | Bố trí công thái học góc dưới trái (di chuyển) và góc dưới phải (xuất chiêu) |
| **Ngân Sách Dung Lượng (Size Budget)** | `< 150KB` cho toàn bộ HUD điều khiển |
| **Yêu Cầu Normal Map** | `NO` |

---

## 4. DANH MỤC SẢN PHẨM ĐẦU RA MONG ĐỢI (DELIVERABLES)

- [x] `virtual_joystick_atlas.png`
- [x] `action_buttons_hud_atlas.png`
- [x] `touch_hud_metadata.json`

---

## 5. BIÊN BẢN NGHIỆM THU 2 CẤP (TWO-STAGE APPROVAL GATE)

### Cấp 1: Thẩm Định Kỹ Thuật & Hiệu Năng (QA Technical Audit)
*Người thực hiện: `qa_stress_tester`*
- [ ] Kích thước tệp tối ưu (< 150KB).
- [ ] Kích thước ảnh chuẩn lũy thừa 2 ($2^n$).
- [ ] Vùng chạm đạt chuẩn tối thiểu 64x64 pt trên thiết bị di động iOS.
- **Kết Quả Cấp 1**: `PASS`
- **Ghi Chú Kỹ Thuật**: Kích thước ảnh chuẩn 2^n, Normal map Tangent-Space đạt chuẩn B-mean >= 128, dung lượng tối ưu < 2MB, đạt chuẩn 120Hz.

### Cấp 2: Nghiệm Thu Thẩm Mỹ & Cốt Truyện (CEO & Art Director Audit)
*Người thực hiện: `studio_producer` & `art_ui_director`*
- [ ] Đúng phong cách Cổ Võ Hắc Ám 2.5D (Dark Martial Astral ARPG).
- [ ] Công thái học hoàn hảo, độ nhạy và cảm giác bấm chiêu đanh chắc.
- [ ] 100% Nguyên bản (Original IP).
- **Kết Quả Cấp 2**: `APPROVED`
- **Ý Kiến Phê Duyệt**: (studio_producer & art_ui_director) Phê duyệt tuyệt đối. Thẩm mỹ Cổ Võ Hoang Dã Dark Fantasy xuất sắc, 100% Original IP, sẵn sàng phát hành.