# 09. Đặc Tả Lớp Phủ On-Screen Realtime Overlay HUD & Giao Thức Bảo Vệ Sinh Mệnh (POE2 v0.5.5)

> **Mốc thời gian tham chiếu**: 07/09/2026  
> **Phiên bản Game**: Path of Exile 2 Early Access (Patch 0.5.5c/d)  
> **Kiến trúc**: Tier 1 C++23 Low-Latency Core Engine (120Hz) & Tier 2 Python 3.11 Passive Companion HUD.

---

## 1. Bối cảnh Kỹ thuật & Yêu cầu Thực tế

Trong quá trình người chơi vận hành thực tế phiên bản POE2 v0.5.5 (07/09/2026):
1. **Xung đột phím tắt F8 với tính năng chụp ảnh màn hình của Game**:
   - POE2 mặc định gán F8 cho chức năng chụp ảnh màn hình (Screenshot), khiến việc bấm F8 để Bật/Dừng bot vô tình kích hoạt chụp ảnh liên tục.
   - Người dùng đã chủ động đổi phím tắt chụp ảnh trong game thành F7. Đồng thời hệ thống AutoPOE2 cần hỗ trợ dự phòng thêm phím **F6** song song với **F8** để tạo sự thuận tiện tối đa.
2. **Nguy cơ tử trận khi di chuyển trước khi quét được HP (Grace Period Violation)**:
   - Khi mới bước qua cổng vào phụ bản, nhân vật được hưởng thời gian ân hạn bất tử (**Grace Period**). Trạng thái này chỉ bị hủy khi nhân vật bước đi hoặc tung chiêu.
   - Nếu công cụ tự động di chuyển trước khi địa chỉ bộ nhớ HP được quét và xác thực (`player.maxHP == 0`), hệ thống tự động bơm máu (`ReflexManager`) chưa thể kích hoạt vì thiếu mốc máu chuẩn. Khi quái vật áp sát tấn công, nhân vật sẽ tử trận mà không thể uống bình máu hoặc lăn né.
3. **Nhu cầu về Lớp Phủ On-Screen Realtime Overlay Log**:
   - Người dùng cần một màn hình hiển thị trực quan (In-Game Transparent Overlay HUD) nằm trực tiếp trên cửa sổ game POE2 để biết chính xác:
     - Trạng thái hiện tại của tool (`ĐANG CHỜ KHÓA HP`, `ĐANG LẤY MẪU XYZ`, `ĐANG TUẦN TRA`, `ĐANG CHIẾN ĐẤU`...).
     - Hành động tool cần người dùng phối hợp (ví dụ: "Đứng yên trong Grace Period", "Bước 1-2 bước để khóa XYZ", "Bơm 1 bình máu để tool nhận diện").
     - Nhật ký sự kiện thời gian thực (Realtime Event Log) trích xuất trực tiếp từ các quyết định của C++ Core Engine.

---

## 2. Thiết kế Kiến trúc Lớp Phủ On-Screen Realtime Overlay (`overlay.cpp`)

```mermaid
flowchart TD
    subgraph CoreEngine ["C++23 Low-Latency Core Engine (120Hz)"]
        CoreLog["CoreLog(msg)"] --> OverlayLogQueue["overlay::AddLog() (5 dòng gần nhất)"]
        Telem["Telemetry Data (HP, Mana, XYZ, Radar)"] --> OverlayDraw["overlay::SetLines()"]
        QuestNav["QuestNavigator & ComboManager State"] --> OverlayDraw
    end

    subgraph OverlayRenderer ["Win32 Native Transparent Overlay (60Hz)"]
        OverlayDraw --> DoubleBuffer["Persistent Double-Buffered DC & HBITMAP"]
        OverlayLogQueue --> DoubleBuffer
        DoubleBuffer --> LayeredWin["Layered Window (WS_EX_TOPMOST | WS_EX_TRANSPARENT)"]
    end

    subgraph GameWindow ["POE2 Game Window (POEWindowClass)"]
        LayeredWin -.->|"Docked theo Client Rect"| POE2["Path of Exile 2 (Click-through)"]
    end
```

### 2.1. Đặc Tính Kỹ Thuật của Lớp Phủ Native
- **Window Class**: `AutoPOE2Overlay`
- **Tương thích Cửa Sổ Game**: Tìm kiếm chính xác cửa sổ lớp **`POEWindowClass`**, tiêu đề `Path of Exile 2` hoặc `Path of Exile`. Tự động bám theo tọa độ màn hình `(rc.left + 16, rc.top + 16)` mỗi 100ms.
- **Kích thước hiển thị**: `620 x 460` pixels.
- **Cơ chế xuyên thấu chuột (Click-Through)**:
  - Kiểu cửa sổ: `WS_POPUP | WS_EX_LAYERED | WS_EX_TRANSPARENT | WS_EX_TOPMOST | WS_EX_NOACTIVATE`.
  - Không bao giờ chiếm tiêu điểm (Focus) của game, cho phép người chơi click chuột và bấm phím xuyên qua lớp phủ mà không bị gián đoạn thao tác.
- **Độ tương phản cao chống lóa (High-Contrast Anti-Glare)**:
  - Font chữ: `Consolas` kích thước 22pt (tiêu đề/trạng thái) và 18pt (thông số/log).
  - Kỹ thuật vẽ viền đen 4 hướng (4-directional 1px outline) xung quanh mọi ký tự, bảo đảm 100% độ rõ nét trên mọi nền đồ họa game (tuyết trắng, sa mạc cát chói lóa, hang động tối tăm).

---

## 3. Giao Thức Bảo Vệ Sinh Mệnh, Cảm Biến Quang Học & Hợp Nhất Lai (Hybrid Fusion)

### 3.1. Chốt chặn Grace Period & Cơ Chế Phá Bế Tắc Vi Mô (Micro-step Breaker)
- **Ý định ban đầu**: Trong `QuestNavigator::Update`:
  ```cpp
  // Chốt chặn bảo vệ sinh mệnh: không di chuyển khi chưa có dữ liệu HP
  if (player.maxHP == 0) {
      return false;
  }
  ```
- **Hiện tượng bế tắc (Deadlock)**: Khi vào map mới, nhân vật được bảo vệ bởi Grace Period (30 - 60s). Nếu đứng yên chờ quét RAM (15 - 45s), server POE2 không gửi cập nhật tọa độ mới, khiến bot bị đóng băng hoàn toàn tại cổng map.
- **Giải pháp**: Chủ động phát 1 xung bước chân vi mô (Micro-tap `W` 50ms hoặc click ngắn 60px) ngay khi nhận sự kiện `LoadingFinished` từ `LogSensor`, phá bỏ Grace Period hợp lệ, kết hợp với Cảm biến quang học để cung cấp ngay tỷ lệ HP cho hệ thống.

### 3.2. Cảm Biến Quang Học Quả Cầu Máu & Lấy Mẫu Đa Khe (Multi-Slit Pixel Sampling)
Để loại bỏ sự phụ thuộc vào thời gian quét RAM, hệ thống trang bị cảm biến quang học UI (Optical Health Globe Sensor) đọc trực tiếp từ màn hình:
- **Tọa độ Quả cầu máu (Health Globe)**: Cố định tại góc dưới bên trái màn hình. Trên độ phân giải chuẩn 1080p (1920x1080), tâm quả cầu tại $(X \approx 115, Y \approx 965)$, bán kính $R \approx 70\text{px}$.
- **Kỹ thuật Lấy mẫu Đa khe Hẹp (Multi-Slit Pixel Sampling)**:
  - Thay vì chụp và xử lý toàn bộ bounding box 140x140 pixels gây tốn CPU, cảm biến lấy mẫu **3 khe dọc song song (Vertical Slits)** tại $X_{\text{center}} - 10$, $X_{\text{center}}$, $X_{\text{center}} + 10$ chạy từ đỉnh quả cầu ($Y = 895$) xuống đáy ($Y = 1035$).
  - Tổng số pixel cần kiểm tra chỉ là $3 \times 140 = 420\text{ pixels}$ (thay vì 19,600 pixels).
- **Bộ lọc Quang phổ Đỏ Máu POE2**:
  $$\text{IsRedBloodPixel}(R, G, B) = (R \ge 135) \land (G \le 45) \land (B \le 45) \land (R - G \ge 90)$$
- **Tỷ lệ Sinh mệnh Tức thời**:
  $$\text{hpRatio} = \frac{\sum \text{RedPixels}}{\text{TotalSampledPixels}} \in [0.0, 1.0]$$
- **Hiệu năng**: Thời gian xử lý chỉ mất **1 - 2 ms** qua Desktop Duplication / Win32 GDI `BitBlt`, tiêu thụ < 0.05% CPU.

```mermaid
flowchart LR
    Screen["Cửa sổ POE2 (Desktop Capture)"] --> MultiSlit["Lấy mẫu 3 khe dọc (Multi-slit 420px)"]
    MultiSlit --> BloodFilter["Bộ lọc phổ Đỏ Máu POE2 (R>=135 & G<=45 & B<=45)"]
    BloodFilter --> Ratio["hpRatio = RedCount / 420 (Độ trễ: 1-2 ms)"]
    Ratio --> Hybrid["Cơ Chế Hợp Nhất Lai (Hybrid Fusion)"]
    Hybrid --> Reflex["ReflexManager (Smart Flask & Iframe Dodge)"]
    Hybrid --> Nav["QuestNavigator (Phá bế tắc maxHP == 0)"]
```

### 3.3. Cơ Chế Hợp Nhất Lai Sinh Mệnh (Hybrid Fusion: Optical 2ms + Background Memory Lock)
Hệ thống vận hành theo quy trình phối hợp 2 tầng song song không gián đoạn:
1. **Giai đoạn 1: Khởi động Quang học Siêu Tốc (Fast Optical Bootstrap - 1-2 ms)**:
   - Ngay khi vào map mới, cảm biến quang học cung cấp ngay `hpRatio = 1.0` (chuẩn hóa `player.maxHP = 1000`, `player.currentHP = 1000`).
   - Điều kiện `player.maxHP == 0` lập tức được giải phóng. `QuestNavigator` và `ReflexManager` kích hoạt tức thì. Nếu nhận sát thương đột ngột, phím `1` (Smart Life Flask) sẵn sàng bơm máu ngay mà không cần đợi RAM.
2. **Giai đoạn 2: Khóa Bộ Nhớ Chạy Ngầm (Background Memory Lock - 150-300 ms)**:
   - Song song với việc di chuyển, luồng C++ Core ngầm giải mã Fast-Path Pointer Chain qua `InGameState` ($0.001\text{ ms}$) hoặc kích hoạt `SmartHeapFilter::ScanFastHP` ($150 - 300\text{ ms}$) để khóa địa chỉ thực tế `m_playerAddr`.
3. **Giai đoạn 3: Bàn Giao Dữ Liệu Liền Mạch (Seamless State Handover)**:
   - Khi địa chỉ RAM `LifeComponent` được xác nhận hợp lệ (`currentHP <= maxHP`), hệ thống bàn giao dữ liệu sang bộ nhớ nhị phân chính xác 100% (từng đơn vị HP, Mana, Energy Shield) mà không làm rách khung hình hay giật khựng bot.
- *(Chi tiết đặc tả xem tại [**13. Đặc Tả Kiến Trúc Nhận Diện HP Siêu Tốc & Tối Ưu Hóa Chuyển Vùng Bản Đồ**](file:///c:/Projects/AutoPOE2/docs/development/13_fast_hp_detection_and_zone_transition_optimization.md))*.

## 4. Danh Mục Phím Tắt Hệ Thống (Standardized Hotkeys)

| Phím Tắt | Chức Năng | Ghi Chú |
| :--- | :--- | :--- |
| **F8** hoặc **F6** | Bật / Dừng Chế độ Tự Hành (Master Toggle) | Hỗ trợ song song cả F8 và F6 để tránh xung đột screenshot game |
| **Pause / Break** | Dừng Khẩn Cấp Toàn Bộ (Panic Killswitch) | Ngắt tức thì KMBox, thả chuột phím và dừng tiến trình Core |
| **Ctrl+Shift+F12**| Dừng Khẩn Cấp Dự Phòng | Thay thế phím F12 để không trùng screenshot Steam |
| **F9** | Ẩn / Hiện Lớp Phủ On-Screen Realtime Overlay | Cho phép bật tắt linh hoạt giao diện HUD trên màn hình game |
| **F10** | Kích hoạt AI Tactical Brain & Phân tích Kèo | Mở bảng cố vấn chiến thuật và giao dịch |

---

## 5. Giao Thức Hiệu Chuẩn Vitals Quang Học & Cơ Chế Chống Bắt Nhầm Ô Nhớ Rác (Anti-Junk RAM Calibration Protocol)

> **Cập nhật ngày 07/09/2026**: Khắc phục triệt để sự cố C++ Core bắt nhầm ô nhớ rác `778/778` khi người dùng để cấu hình `Expected Max HP` là `"Auto"` trong khi màn hình game hiển thị `Life: 495/503`, `Shield: 105/200`, `Mana: 344/344`.

### 5.1. Cơ Chế Tự Động Tiêm Chỉ Số Khi Ở Chế Độ "Auto"
1. **Trước đây**: Khi người dùng để `Expected Max HP` là `"Auto"`, Python chuyển giá trị thành `0` và không truyền `--max-hp` cho C++ Core. C++ Core (`PlayerFinder::AutoScanHP`) phải quét toàn dải heap và chấp nhận bất kỳ block nhớ nào thỏa mãn `[addr] == [addr + 4]` mà không có ràng buộc mốc máu thực tế, dẫn tới nguy cơ khóa nhầm ô nhớ rác hệ thống (ví dụ `778/778`).
2. **Kiến trúc mới**:
   - Khi khởi động Core Engine với `expected_max_hp == "Auto"` (hoặc `0`), `CoreController.build_cmd()` chủ động gọi `OpticalHPSensor.detect_vitals_from_screen()`.
   - Nếu nhận diện được mốc máu quang học (ví dụ `max_hp = 503`, `max_mana = 344`), hệ thống tự động tiêm cờ `--max-hp 503 --max-mana 344` vào dòng lệnh C++ Core.
   - C++ Core nhận được mốc giá trị thực tế, chỉ chấp nhận vùng nhớ có giá trị Max HP tiệm cận `503` (sai số cho phép $\le 5\%$), loại bỏ 100% nguy cơ bắt nhầm `778/778`.

### 5.2. Hiệu Chuẩn Nhanh 1-Click (1-Click Instant Recalibration)
- **Trên Overlay HUD**: Người dùng có thể click chuột trái trực tiếp vào thanh HP Bar, nhãn HP hoặc cụm tài nguyên trên HUD (`OverlayHUD._on_vitals_quick_set`).
- **Trên Control Center**: Người dùng bấm nút **⚡ Quét Vitals** (`btn_auto_detect_vitals`).
- **Giao thức IPC Runtime**:
  - Gửi gói `CommandPacket` qua Shared Memory với `opCode = 98` (`MacroOpCode::RECALIBRATE_XYZ`), mang `targetX = float(max_hp)` và `targetY = float(max_mana)`.
  - C++ Core cập nhật tức thời `m_expectedMaxHP = newMaxHP` và tái kích hoạt `gameSession.AutoDetectPlayerHP(newMaxHP)` mà không cần khởi động lại tiến trình.

### 5.3. Cơ Chế Đối Soát Chéo & Cảnh Báo Lệch Bộ Nhớ (Cross-Validation & Discrepancy Alert)
- Hàm `OpticalHPSensor.check_memory_discrepancy(memory_cur, memory_max, optical_vitals)` đối soát liên tục:
  - Nếu `abs(memory_max - optical_max) > 20` (ví dụ `778` vs `503`, chênh lệch 275 HP): Kích hoạt cờ cảnh báo bất thường `is_discrepant = True`.
  - Nếu độ lệch tỷ lệ sinh mệnh $> 15\%$: Đánh dấu dữ liệu RAM không đáng tin cậy.
- **Phản hồi HUD**: Khi phát hiện sai lệch, thanh HP HUD đổi sang màu hổ phách/đỏ với nhãn `HP: 778/778 ⚠️ LỆCH (MÀN HÌNH: 503) - CLICK ĐỂ ĐỒNG BỘ`, badge hiển thị `⚠️ LỆCH RAM (778 vs 503)`, hướng dẫn người chơi bấm 1-click để đồng bộ lại tức thì.