# Đặc Tả Kỹ Thuật: Tối Ưu Hóa Thuật Toán Tìm Đường JPS, Bản Đồ Nhiệt Thám Hiểm & Tự Hành Kịch Bản Map Tối Tốc

- **Mã Tài Liệu**: `DOC-DEV-2026-038`
- **Mốc Thời Gian / Phiên Bản Tham Chiếu**: `12/09/2026` - POE2 0.5.x / Endgame Atlas Progression
- **Trạng Thái**: `IMPLEMENTED`
- **Tác Giả**: Intelligent Orchestrator Agent (AutoPOE2 Core Engine)
- **Module Ảnh Hưởng**: `src/core/navigation/` (`Pathfinder`, `QuestNavigator`, `TerrainGrid`), `tests/test_core.cpp`

---

## 1. Bối Cảnh & Vấn Đề Kỹ Thuật (Background & Technical Problem)

### 1.1. Hiện Trạng Cũ & Các Điểm Nghẽn Thời Gian
1. **Độ Trễ Tính Toán Đường Đi (Pathfinding CPU Bottleneck)**:
   - Thuật toán tìm đường trước đây là **Grid A\* 8 hướng** truyền thống. Trên lưới bản đồ địa hình $256 \times 256$ ô (kích thước ô 6.0 units, bán kính phủ ~1500 units), việc duyệt qua hàng nghìn ô trống đối xứng khiến số lượng node đưa vào Priority Queue lên tới 1500 – 3500 nodes.
   - Thời gian tính toán dao động từ 2.5ms – 8.0ms mỗi lần tìm đường dài. Điều này đe dọa nghiêm trọng chu kỳ 120Hz (~8.33ms) của Core Hot Path, gây trễ các phản xạ sinh tồn (Auto-Flask, Dodge Roll, Emergency Logout).
2. **Khựng Giật Khi Di Chuyển (Movement Deceleration Stutter)**:
   - Trong chế độ di chuyển bằng chuột (`MovementMode::MOUSE`), tham số `effectiveInterval` bị ép cứng ở mức 650ms. Nhân vật chạy được một đoạn ngắn rồi khựng lại, đợi nhịp click tiếp theo mới chạy tiếp, làm giảm 35% – 45% tốc độ trung bình khi qua map.
3. **Thiếu Trí Nhớ Vùng Đã Khám Phá (Lack of Visited Trail Memory)**:
   - Cơ chế tuần tra `autoPatrol` (Frontier Momentum) chỉ dựa vào khoảng cách tới cổng vào `distFromEntry` và thử nghiệm 5 góc ngẫu nhiên mỗi 2.8s. Khi gặp ngõ cụt, địa hình chữ U/chữ L hoặc mê cung, bot dễ bị quay đầu hoặc đi quẩn lại các vùng đã thám hiểm, khiến thời gian dọn 1 map kéo dài tới 5 – 10 phút.
4. **Kịch Bản Map Chưa Được Khai Thác Đầy Đủ**:
   - Chế độ `FAST_CLEAR` dừng lại trước MỌI con quái lẻ loi trong cự ly 380u (giống hệt chế độ cày exp thông thường).
   - Chế độ `ATLAS_QUEST_RUSH` chưa được đấu nối với `AreaEventManager`, không tự động khóa và chạy thẳng tới các sự kiện nhiệm vụ Atlas (Citadel, Breach, Ritual, Essence, Delirium).

---

## 2. Kiến Trúc Giải Pháp & Thiết Kế Kỹ Thuật (Architectural Solutions)

### 2.1. Jump Point Search (JPS) & Any-Angle Line-of-Sight Funnel
- **Nguyên lý JPS trên Uniform-Cost Grid**:
  - Tận dụng đặc tính địa hình phẳng đồng nhất của bản đồ POE2, JPS loại bỏ triệt để các đường đi đối xứng (symmetric paths).
  - Thay vì đẩy từng ô lân cận vào OpenSet, hàm `Jump(x, y, dx, dy)` phóng tia trực tiếp theo phương di chuyển:
    - **Phương thẳng** ($dx \ne 0, dy = 0$ hoặc $dx = 0, dy \ne 0$): Nhảy dọc theo đường thẳng cho tới khi gặp vật cản hoặc phát hiện **Forced Neighbor** (ô vật cản nằm sát bên sườn có ô đi được ngay phía sau).
    - **Phương chéo** ($dx \ne 0, dy \ne 0$): Nhảy theo góc $45^\circ$, tại mỗi bước gọi đệ quy kiểm tra 2 phương thành phần (ngang và dọc). Nếu một trong hai phương tìm thấy Jump Point hoặc đích, ô hiện tại lập tức trở thành Jump Point.
- **Any-Angle Funnel Smoothing**:
  - Danh sách Jump Points sau đó được kéo thẳng dây (Bresenham Raycast qua `TerrainGrid::HasLineOfSight`) để tạo ra đường đi thẳng tự nhiên, loại bỏ hoàn toàn các khúc cua gập ghềnh $45^\circ$.
- **Hiệu quả định lượng**:
  - Thời gian tính toán giảm từ $3.5\text{ms}$ xuống **$< 0.25\text{ms}$** (nhanh hơn 15x – 30x).
  - Số lượng node duyệt giảm $> 90\%$.

### 2.2. Động Cơ Di Chuyển Thông Minh Liên Tục (Continuous Dynamic Cadence)
- **Cơ chế nhịp click thích ứng (Adaptive Cadence)**:
  - Khi nhân vật đang có đường thẳng thông thoáng phía trước (khoảng cách tới waypoint tiếp theo $\ge 100$ units và không có vật cản):
    - Tần suất gửi click di chuyển được hạ xuống **$200\text{ms}$** (`fastMoveIntervalMs`).
    - Tọa độ click được chiếu xa quanh tâm màn hình theo góc hướng đi thông qua `HumanCurveGenerator` để tạo chuyển động mượt mà, nhân vật duy trì tốc độ chạy tối đa liên tục không bị giảm tốc.
  - Khi tới gần mục tiêu nhiệm vụ hoặc tương tác ($< 35$ units): Tự động giãn nhịp sang chế độ click chính xác (cadence $450\text{ms}$) để click chuẩn xác vào NPC/Portal/Rương.
- **Tận dụng Kỹ Năng Cơ Động Đường Trường (Mobility Skill Travel)**:
  - Khi đường thẳng phía trước thông thoáng dài ($> 240$ units), không có quái vật nguy hiểm chặn đầu, nhân vật đang ở 100% sinh lực/ES và cooldown $\ge 2800\text{ms}$, bot kích hoạt Dodge Roll (Spacebar) hoặc phím lướt để tăng tốc độ di chuyển trên đường dài.

### 2.3. Bản Đồ Nhiệt Thám Hiểm (Exploration Heatmap & Frontier Momentum 2.0)
- **Cấu trúc dữ liệu**:
  - Lưới bản đồ nhiệt $64 \times 64$ ô (`m_visitedHeatmap`) bao phủ khu vực cục bộ quanh người chơi.
  - Mỗi tick di chuyển, tọa độ người chơi được ghi nhận qua `RecordPlayerPosition()`, tăng chỉ số nhiệt độ đã thăm của ô tương ứng.
- **Hàm đánh giá hướng thám hiểm (Frontier Scoring Function)**:
  $$\text{Score}(\theta) = 500 \times \text{IsWalkable} + 3.0 \times \Delta\text{DistFromEntry} - 80.0 \times \text{VisitCount} - 400 \times \text{BacktrackPenalty}$$
  - Hướng nào đã bị đi qua nhiều lần (`VisitCount > 0`) sẽ bị phạt điểm nặng nề, buộc thuật toán luôn chọn hướng tiến vào **vùng chưa từng khám phá (Unvisited Frontier)**.
  - Loại bỏ hoàn toàn việc bot bị kẹt trong các ngõ cụt hoặc chạy quẩn quanh các phòng đã dọn.

### 2.4. Động Cơ Phân Hóa 4 Kịch Bản Map Endgame
1. **`MapScenario::BOSS_RUSH`**:
   - Mục tiêu: Hạ Boss map trong thời gian ngắn nhất (60 - 90s) để mở điểm Atlas Passive.
   - Sải bước nhanh $240\text{u}$.
   - Tự động nhận diện Arena Gate (Type 3 với các từ khóa: `Arena`, `Lair`, `Chamber`, `Sanctum`, `Throne`, `Boss`, `Gate`) từ xa và chuyển sang chế độ **Beeline Sprint** chạy thẳng tới cổng.
   - Bỏ qua 100% quái rác trắng/magic, chỉ dừng khi quái là Boss hoặc chặn đường ở cự ly quá gần ($< 85\text{u}$).
   - Sau khi Boss chết: Chờ $2.5\text{s}$ nhặt loot giá trị -> Tự động mở Town Portal (phím T) về Hideout.
2. **`MapScenario::ATLAS_QUEST_RUSH`**:
   - Tích hợp trực tiếp với `AreaEventManager`: Quét danh sách Candidate/Committed Events (Type 5 - 11: Citadel, Breach, Ritual, Essence, Shrine, Strongbox).
   - Tự động ưu tiên dẫn đường bằng JPS thẳng tới vị trí Event gần nhất. Sau khi xử lý xong các sự kiện, tự động chuyển sang săn Boss để hoàn tất map.
3. **`MapScenario::FAST_CLEAR`**:
   - **Phân tích mật độ cụm quái (Pack Density Clustering)**: Quét các quái vật trong cự ly $350\text{u}$.
   - Nếu cụm quái $< 3$ con và không có quái Rare/Unique (`rarity < 2`), coi là quái rác lẻ tẻ, KHÔNG dừng tuần tra, tiếp tục chạy dọn trên trục chính.
   - Chỉ dừng xả combo khi mật độ cụm $\ge 3$ quái hoặc có quái Rare/Unique.
4. **`MapScenario::FULL_CLEAR`**:
   - Dùng Exploration Heatmap quét sạch 100% sương mù bản đồ (Fog of War) và theo dõi số lượng quái còn lại thông qua sự kiện `MonstersRemain`.

---

## 3. Hợp Đồng Bất Biến & Chống Hồi Quy (Invariants & Regression Gates)

- **INV-NAV-01**: Thời gian tính toán đường đi JPS cho khoảng cách 100 units trên `TerrainGrid` phải $\le 0.35\text{ms}$.
- **INV-NAV-02**: Không có bất kỳ waypoint nào của JPS hoặc Any-Angle Funnel cắt ngang qua ô vật cản (`!IsWalkableGrid`).
- **INV-NAV-03**: Trong chế độ `FAST_CLEAR`, tồn tại 1-2 quái trắng trong tầm $350\text{u}$ không được làm ngắt quãng di chuyển.
- **INV-NAV-04**: Trong chế độ `ATLAS_QUEST_RUSH`, nếu tồn tại sự kiện trong `AreaEventManager`, bot phải chọn tọa độ của sự kiện làm mục tiêu ưu tiên số 1 thay vì tuần tra ngẫu nhiên.
- **INV-NAV-05**: Khi mất focus cửa sổ game (`EnsurePoe2WindowFocus() == false`), toàn bộ chuột và phím di chuyển phải bị khóa chặn tức thì.