# Poe2VisualTool

**Standalone Camera, Minimap Shader & Item Inspector Utility for Path of Exile 2**  
*Mốc thời gian tham chiếu kỹ thuật: 13/09/2026 | Kiến trúc chuẩn: Two-Tier Asymmetric Hybrid (C++23 / Python 3.11)*

---

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Platform: Windows 10/11 x64](https://img.shields.io/badge/Platform-Windows%2010%2F11%20x64-0078D6.svg)](https://microsoft.com)
[![DirectX: 12 Agility SDK](https://img.shields.io/badge/DirectX-12%20Agility-red.svg)](https://devblogs.microsoft.com/directx/)
[![Architecture: Two--Tier Asymmetric Hybrid](https://img.shields.io/badge/Architecture-Two--Tier%20Hybrid%20120Hz-success.svg)](docs/architecture.md)

---

## 1. Giới Thiệu Tổng Quan (Overview)

**Poe2VisualTool** là bộ công cụ tối ưu hóa trải nghiệm hình ảnh (Quality of Life - QoL) độc lập 100% dành riêng cho **Path of Exile 2**. 

### 🛡️ Nguyên Tắc Thiết Kế: Thuần QoL & An Toàn Tuyệt Đối (Pure QoL & Account Safety)
- **100% Không Botting / Automation**: Poe2VisualTool hoàn toàn **không** chứa bất kỳ logic tự động điều khiển nào (không tự động click chuột, không tự động uống bình máu/mana, không tự động thi triển kỹ năng hay nhặt đồ).
- **Trực quan hóa & Công thái học (Visuals & Ergonomics)**: Tập trung duy nhất vào việc mở rộng tầm quan sát, loại bỏ sương mù gây mỏi mắt, làm sáng bản đồ địa hình và phân loại màu sắc chỉ số vật phẩm trực tiếp trong bộ nhớ.
- **Zero In-Game Code Injection**: Không hook API nhạy cảm vào DirectX swapchain rendering thread, không can thiệp vào máy chủ game (Server-side packets).
- **1-Frame Panic Restore**: Tích hợp cơ chế khôi phục bộ nhớ nguyên bản chỉ trong đúng 1 khung hình (**< 8.33ms @ 120Hz**), hoàn toàn không để lại dấu vết khi người dùng yêu cầu ngắt kết nối.

---

## 2. Danh Sách Tính Năng Cốt Lõi (Core Features)

### 1. Native 3D Scene Camera Wheel Zoom (1.0x – 8.0x)
- Cho phép điều khiển khoảng cách camera linh hoạt bằng con lăn chuột (`Ctrl + Mouse Wheel`) hoặc phím tắt chuyên dụng từ góc nhìn mặc định `1.0x` lên đến `8.0x`.
- **Dynamic zFar Culling Fix**: Tự động tính toán lại ma trận chiếu (`Projection Matrix`) và đẩy xa mặt phẳng cắt `zFar` tương ứng với khoảng cách camera, triệt tiêu hoàn toàn hiện tượng đen màn hình (black void) hoặc biến mất mesh địa hình khi zoom xa.

### 2. Volumetric & Atlas Fog Removal
- Vô hiệu hóa lớp sương mù thể tích (Volumetric Fog) và sương mù địa hình (Height Fog) gây cản trở tầm nhìn trong các khu vực ngục tối (Dungeons), đầm lầy (Sandswept Marsh) hay bản đồ rừng rậm.
- Tăng cường độ tương phản hình ảnh và độ rõ nét của các chi tiết môi trường mà không làm giảm tốc độ khung hình (Zero FPS drop).

### 3. Always-On In-Map Minimap Auto-Reveal & Triad DirectX 12 Shader Patches
- **Xóa sổ viền xanh Cyan**: Vô hiệu hóa triệt để lưới khung dây viền minimap màu xanh thô kệch (`m_pMinimapQuadWireframe` bypass).
- **100% Terrain Full-Discovery**: Mở sáng toàn bộ địa hình bản đồ (Terrain Texture Map) ngay khi vừa bước vào khu vực, giải phóng người chơi khỏi việc phải chạy men theo từng góc tường để dò đường.
- **Direct Map Content Display**: Làm nổi bật và hiển thị vị trí các yếu tố quan trọng trên bản đồ: Hòm đồ (Strongboxes), Đền thờ (Shrines), Trùm khu vực (Bosses), và các cơ chế đặc thù (League Mechanics).

### 4. In-Place Native Item Modifier Color Replacement (PoE Smoother Style)
- Can thiệp trực tiếp vào bảng mã màu modifier vật phẩm (in-memory modifier font color tokens), tái phân loại màu sắc các dòng chỉ số trực quan:
  - 🔴 **Màu Đỏ**: Các chỉ số Sát thương Vật lý / Tấn công / Xuyên giáp (Physical & Attack mods).
  - 🔵 **Màu Lam**: Các chỉ số Phép thuật / Hồi Mana / Tốc độ thi triển (Caster, Spell & Mana mods).
  - 🟢 **Màu Xanh lục / Cyan**: Tốc độ di chuyển / Né tránh / Kháng nguyên tố (Speed, Evasion & Resistance).
  - 🟡 **Màu Vàng Kim / Cam**: Các dòng modifier bậc cao nhất (Tier 1), chỉ số đặc biệt hoặc Influenced mods.

### 5. Smart 4-Tier Game Path Resolution
Tự động giải quyết đường dẫn cài đặt game Path of Exile 2 thông qua thuật toán 4 tầng thông minh:
1. **Tier 1 - Process Inspection**: Quét tiến trình đang chạy (`PathOfExileSteam.exe` hoặc `PathOfExile.exe`) bằng Win32 API.
2. **Tier 2 - Persistent Cache**: Nạp đường dẫn hợp lệ đã lưu từ tệp cấu hình `config.toml`.
3. **Tier 3 - Registry & Multi-Drive Steam VDF**: Đọc Windows Registry và phân tích tệp `libraryfolders.vdf` để tự động quét qua mọi phân vùng ổ cứng (C:, D:, E:, M.2 NVMe, v.v.).
4. **Tier 4 - Native File Dialog**: Tự động hiển thị hộp thoại duyệt tệp chuẩn Windows (`IFileOpenDialog`) khi không tìm thấy đường dẫn, sau đó tự động lưu lại cho các lần khởi chạy kế tiếp.

### 6. 1-Frame Panic Restore (F12 / Pause)
- Được điều khiển bởi cấu trúc dữ liệu nguyên tử lock-free.
- Khi nhấn phím khẩn cấp (`Pause` hoặc `F12`), toàn bộ các byte vá (patches) trên bộ nhớ game được khôi phục về trạng thái nguyên bản 100% trong vòng **< 8.33ms**.
- Đảm bảo an toàn tuyệt đối khi người dùng muốn đưa client game về trạng thái nguyên thủy ngay lập tức.

---

## 3. Bảng Phím Tắt In-Game (In-Game Hotkey Bindings)

| Phím Tắt | Chức Năng | Mô Tả Chi Tiết |
| :--- | :--- | :--- |
| **`Pause` / `F12`** | **Panic Restore** | Khôi phục ngay lập tức 100% byte gốc của game trong < 8.33ms |
| **`Ctrl` + `Mouse Wheel`** | **Camera Smooth Zoom** | Phóng to / thu nhỏ camera mượt mà (dải zoom từ 1.0x đến 8.0x) |
| **`Page Up`** | **Camera Zoom In** | Thu gần camera thêm 0.5x |
| **`Page Down`** | **Camera Zoom Out** | Đẩy xa camera thêm 0.5x |
| **`Home`** | **Camera Reset** | Đưa camera quay về góc nhìn mặc định gốc (1.0x) |
| **`F5`** | **Toggle Fog Removal** | Bật / tắt tính năng xóa sương mù thể tích & sương mù bản đồ |
| **`F6`** | **Toggle Minimap Reveal** | Bật / tắt mở sáng toàn bộ minimap & vá shader địa hình |
| **`F7`** | **Toggle Item Colorizer** | Bật / tắt phân loại màu sắc modifier trang bị |
| **`Ctrl` + `F11`** | **Reload Config** | Tải lại cấu hình `config.toml` thời gian thực |

---

## 4. Hướng Dẫn Cài Đặt & Biên Dịch (Build & Setup Guide)

### 4.1. Yêu Cầu Môi Trường (Prerequisites)
- **Hệ điều hành**: Windows 10 hoặc Windows 11 (64-bit).
- **Trình biên dịch**: Visual Studio 2022 (MSVC v143 toolset trở lên với cờ hỗ trợ C++23 `/std:c++latest`).
- **CMake**: Phiên bản 3.25 trở lên.
- **Python**: Phiên bản 3.11+ (chỉ cần thiết nếu sử dụng giao diện quản lý bổ trợ Python QoL Companion).

### 4.2. Biên Dịch C++ Native Engine

Mở **PowerShell** hoặc **Developer Command Prompt for VS 2022** tại thư mục gốc dự án:

```powershell
# 1. Tạo thư mục cấu hình CMake
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release

# 2. Biên dịch dự án ở chế độ Release
cmake --build build --config Release
```

Sau khi biên dịch hoàn tất, tệp thực thi độc lập sẽ xuất hiện tại:
`c:\Projects\Poe2VisualTool\bin\Poe2VisualTool.exe`

### 4.3. Khởi Chạy Công Cụ (Running the Tool)

Có 2 phương thức khởi chạy:
1. **Chạy trực tiếp file thực thi**:
   - Nhấp đúp chuột vào `bin\Poe2VisualTool.exe` (hoặc chạy qua PowerShell với quyền Administrator nếu client game chạy với quyền Admin).
2. **Chạy qua kịch bản tự động**:
   - Nhấp đúp vào file `run_tool.bat` tại thư mục gốc. Kịch bản sẽ tự động kiểm tra tiến trình game, giải quyết đường dẫn theo cơ chế 4 tầng và kích hoạt engine.

---

## 5. Cấu Trúc Thư Mục Dự Án (Project Structure)

```
c:\Projects\Poe2VisualTool\
├── bin/                             # Tệp nhị phân sau biên dịch (.exe, .dll)
├── config/                          # Tệp cấu hình mặc định (config.toml, offsets.toml)
├── docs/                            # Tài liệu đặc tả kỹ thuật chi tiết
│   ├── architecture.md              # Đặc tả kiến trúc Two-Tier Asymmetric Hybrid
│   └── smart_game_path_resolution_spec.md # Đặc tả cơ chế dò đường dẫn 4 tầng
├── src/
│   ├── core/                        # Tầng C++23 Native Hot Path Engine (120Hz)
│   │   ├── common/                  # Types, Logger, Win32 Wrappers, Math
│   │   ├── memory/                  # Pattern Scanner, Memory Patch, Panic Buffer
│   │   └── visual/                  # Camera, Minimap Shader, Fog, Item Inspector
│   ├── assistant/                   # Tầng Python Companion (Cold Path 1-30Hz)
│   │   ├── config_ui/               # Giao diện tùy biến màu sắc và phím bấm
│   │   └── path_resolver/           # Trình giải mã đường dẫn Steam VDF & Registry
│   └── visual_tool/                 # Điểm vào ứng dụng chính (Main Entrypoint)
├── tests/                           # Bộ kiểm thử tự động (Unit & Integration Tests)
├── CMakeLists.txt                   # Cấu hình biên dịch CMake C++23
├── run_tool.bat                     # Script khởi chạy tiện lợi trên Windows
└── README.md                        # Hướng dẫn sử dụng & tổng quan dự án
```

---

## 6. Cam Kết Bất Biến Kỹ Thuật (Architectural Invariants)

- **Zero-Allocation Hot Path**: Vòng lặp xử lý camera và input ở tần số 120Hz tuyệt đối không cấp phát bộ nhớ động (`new`, `malloc`, `std::vector::push_back`).
- **Mechanical Sympathy**: Dữ liệu trao đổi giữa các tiến trình được căn chỉnh 64-byte Cache-Line (`alignas(64)`), loại bỏ hoàn toàn hiện tượng False Sharing.
- **Root-Cause First**: Không dùng các bản vá tạm thời, không hardcode offset mù quáng; toàn bộ offset được xác thực bằng Pattern Scanning động dựa trên chữ ký nhị phân (AOB Sigscan).

---

## 7. Tuyên Bố Miễn Trừ Trách Nhiệm (Disclaimer)

*Poe2VisualTool là phần mềm tiện ích hỗ trợ khả năng tiếp cận và công thái học hình ảnh độc lập, được phát triển nhằm mục đích nghiên cứu kỹ thuật đồ họa và tối ưu hóa hiển thị. Phần mềm không liên kết, không được chứng thực hay ủy quyền bởi Grinding Gear Games. Người dùng tự chịu mọi trách nhiệm đối với việc sử dụng công cụ phù hợp với điều khoản sử dụng của nhà phát hành trò chơi.*