# ĐẶC TẢ KIẾN TRÚC HAI TẦNG BẤT ĐỐI XỨNG POE2VISUALTOOL ## (TWO-TIER ASYMMETRIC HYBRID ARCHITECTURE SPECIFICATION) - **Mã Tài Liệu**: `DOC-ARCH-POE2VISUALTOOL-2026` - **Mốc Thời Gian Tham Chiếu**: `13/09/2026` - **Phiên Bản**: `1.0.0-RELEASE` - **Hệ Thống**: Poe2VisualTool (Path of Exile 2 Visual QoL Utility) - **Chuẩn Mực**: Two-Tier Asymmetric Hybrid (Tier 1: C++23 120Hz Hot Path | Tier 2: Python 3.11 Cold Path) --- ## 1. Triết Lý & Động Lực Thiết Kế Kiến Trúc (Architectural Philosophy) Đối với các tiện ích can thiệp hiển thị thời gian thực (Visual Quality of Life Utilities) trong môi trường game đồ họa DirectX 12 hiện đại như **Path of Exile 2**, hệ thống phải đối mặt với thách thức kỹ thuật nghiêm ngặt: 1. **Độ trễ phản hồi camera & phím bấm**: Phải khớp hoàn toàn với tần số quét màn hình (120Hz ~ 8.33ms/khung hình). Mọi độ trễ (jitter) hay giật khung hình do garbage collection hoặc cấp phát heap đều phá vỡ trải nghiệm mượt mà của người chơi. 2. **Tính độc lập và an toàn tuyệt đối**: Tiện ích phải là phần mềm công thái học thuần túy (Pure Visual QoL), triệt tiêu 100% các thành phần automation/botting để bảo vệ an toàn tài khoản người dùng. 3. **Cơ chế khôi phục khẩn cấp tức thời (1-Frame Panic Restore)**: Khi người dùng cần ngắt can thiệp, toàn bộ các vùng nhớ game đã chỉnh sửa phải được hoàn trả về byte nguyên bản trong vòng chưa đầy 1 khung hình (< 8.33ms). Để giải quyết trọn vẹn các yêu cầu trên, **Poe2VisualTool** áp dụng mô hình **Kiến Trúc Hai Tầng Bất Đối Xứng (Two-Tier Asymmetric Hybrid Architecture)**: - **Tier 1 (Hot Path 120Hz - C++23 Native Engine)**: Đảm nhiệm toàn bộ việc quét mẫu chữ ký (Pattern Scanning), kiểm soát ma trận camera, vá shader DirectX 12 của minimap, triệt tiêu sương mù và duy trì bộ đệm Panic Restore. Không dùng cấp phát động trong vòng lặp runtime, tận dụng tối đa Data-Oriented Design (DOD) và Hexagonal Ports & Adapters. - **Tier 2 (Cold Path 1-30Hz - Python 3.11 Companion HUD)**: Đảm nhiệm các tác vụ bất đồng bộ không nhạy cảm về thời gian: Giao diện người dùng cấu hình bảng màu modifier, bộ giải mã đường dẫn đa phân vùng Steam VDF / Registry, và giám sát trạng thái hệ thống. - **Kênh IPC Bộ Nhớ Chia Sẻ (Shared Memory IPC)**: Giao tiếp lock-free không khóa, dựa trên nguyên lý **Mechanical Sympathy** với cấu trúc Seqlock Double-Buffer và Ring Buffer căn chỉnh 64-byte Cache-Line (`alignas(64)`), đảm bảo 0 torn-read và độ trễ 0ms tranh chấp khóa. --- ## 2. Sơ Đồ Kiến Trúc Tổng Thể (System Architecture Blueprint) ``` ┌────────────────────────────────────────────────────────────────────────────────────────┐ │ TIER 1: C++23 NATIVE ENGINE (HARD REAL-TIME HOT PATH 120HZ) │ │ │ │ [HEXAGONAL IN-PORTS] [DATA-ORIENTED LINEAR PIPELINE] [HEXAGONAL OUT-PORTS]│ │ ┌──────────────────┐ ┌─────────────────────────────┐ ┌───────────────────┐│ │ │ MemoryPort │ ──RPM───> │ 1. Camera Projection Engine │ │ DirectMemoryPatch ││ │ │ (Process/RPM) │ │ (Zoom 1.0x-8.0x, zFar) │──>│ (VirtualProtect) ││ │ ├──────────────────┤ ├─────────────────────────────┤ ├───────────────────┤│ │ │ InputInterlock │ ──Raw───> │ 2. Fog Elimination Pipeline │ │ 1-Frame Panic ││ │ │ (MouseWheel/Keys)│ │ (Volumetric & Atlas Fog) │ │ Rollback Guard ││ │ ├──────────────────┤ ├─────────────────────────────┤ └───────────────────┘│ │ │ SigscanAdapter │ ──AOB───> │ 3. Minimap Shader Controller│ ▲ │ │ │ (Pattern Cache) │ │ (DX12 Quad & Discovery) │ │ │ │ └──────────────────┘ ├─────────────────────────────┤ │ │ │ │ 4. Item Mod Colorizer Engine│ ────────────┘ │ │ │ (In-Place Font Token) │ (Safe Section Bounds) │ │ └──────────────┬──────────────┘ │ └────────────────────────────────────────────────┼───────────────────────────────────────┘ │ [LOCK-FREE SHARED MEMORY IPC] ┌──────────────────────────────┴──────────────────────────────┐ │ • VisualStateTelemetry: Seqlock Double-Buffer (120Hz) │ │ • VisualCommandChannel: Lock-Free SPSC Ring Buffer (16 Slot)│ │ • Memory Alignment: 64-byte Cache-Line Aligned │ │ • Zero-Torn-Read Contract via std::atomic sequence│ └──────────────────────────────┬──────────────────────────────┘ │ ┌────────────────────────────────────────────────┼──────────────────────────────────────┐ │ TIER 2: PYTHON 3.11 QoL COMPANION & CONFIG HUD (COLD PATH 1-30HZ) │ │ │ │ │ ┌───────────────────────▼────────────────────────┐ │ │ │ EVENTBUS & CONFIG DISPATCHER │ │ │ └───────┬─────────────────┬───────────────────┬──┘ │ │ │ │ │ │ │ ┌──────────────▼───┐ ┌──────────▼────────┐ ┌───────▼──────────────┐ │ │ │ SmartPathResolver│ │ Modern Config UI │ │ ItemColorPresetEditor│ │ │ │ (Steam VDF/Reg) │ │ (CustomTkinter) │ │ (Red/Blue/Green/Gold)│ │ │ └──────────────────┘ └───────────────────┘ └──────────────────────┘ │ │ │ │ │ ┌─────────────────────▼───────────────────────┐ │ │ │ PERSISTENT TOML STORAGE │ │ │ │ • config/config.toml │ │ │ │ • config/offsets.toml (Sigscan Cache) │ │ │ └─────────────────────────────────────────────┘ │ └───────────────────────────────────────────────────────────────────────────────────────┘ ``` --- ## 3. Chi Tiết Tầng Tier 1: C++23 Native Hot Path Engine (120Hz) Tier 1 hoạt động với chu kỳ đồng hồ cứng **120Hz (~8.33ms/tick)** bằng cách kích hoạt `timeBeginPeriod(1)` của hệ điều hành Windows. ### 3.1. Tuyến Tính Hóa Vòng Lặp DOD (Data-Oriented Design Pipeline) Mỗi tick 120Hz, luồng xử lý đi qua 4 phân đoạn tuyến tính, không phân nhánh đệ quy, không gọi hàm ảo đa hình: 1. **Pha 1: Input & Focus Interlock Resolution**: - Kiểm tra tiêu điểm cửa sổ game bằng `EnsurePoe2WindowFocus()`. Nếu người dùng đang Alt-Tab sang ứng dụng khác, toàn bộ các can thiệp phím tắt/con lăn chuột lập tức tạm dừng để tránh xung đột thao tác ngoài desktop. - Tiếp nhận sự kiện con lăn chuột và phím tắt thông qua `RawInput` hoặc Windows Hook cục bộ siêu nhẹ. 2. **Pha 2: Camera Matrix & Frustum Adjustment**: - Đọc con trỏ cấu trúc Camera từ base address đã phân giải. - Cập nhật thông số `Distance` (khoảng cách camera) tương ứng với hệ số zoom hiện tại ($1.0\times \dots 8.0\times$). - Đồng thời tính toán lại và ghi đè giá trị mặt phẳng cắt xa (`zFar`) của ma trận chiếu hình khối (`Projection Frustum`), ngăn chặn engine đồ họa culling các mesh đồi núi và công trình ở xa. 3. **Pha 3: Dynamic Shader & Visual State Enforcement**: - Duy trì trạng thái vô hiệu hóa sương mù (Fog Removal). - Kiểm tra trạng thái minimap: Nếu nhân vật chuyển vùng (Zone Transition / Map Load), tự động kích hoạt bộ shader patch để mở sáng bản đồ địa hình (Terrain Reveal) và gỡ bỏ khung viền xanh cyan (`m_pMinimapQuadWireframe`). 4. **Pha 4: Lock-Free Telemetry Export**: - Ghi trạng thái hình ảnh hiện tại (Camera Zoom, Fog State, Minimap Status, Active Mod Color Table) vào bộ nhớ chia sẻ Seqlock Double-Buffer cho Tier 2 đọc. ### 3.2. Cấu Trúc Hexagonal Ports & Adapters của C++ Core Nhằm đảm bảo khả năng kiểm thử độc lập (Headless Test Harness) mà không cần mở game thật: - **`IMemoryPort`**: - `LiveWin32RPMAdapter`: Sử dụng `ReadProcessMemory` và `WriteProcessMemory` với cờ `VirtualProtectEx` an toàn. - `MockMemoryAdapter`: Chạy trên bộ nhớ giả lập tĩnh (Static Dump Array) trong các bài kiểm thử tự động `Poe2VisualTool_Tests`. - **`IPatternScanner`**: - `BoyerMooreHorspoolScanner`: Thuật toán quét chữ ký nhị phân (AOB Sigscan) tối ưu với bảng nhảy ký tự, cho phép quét toàn bộ module `.text` 80MB trong < 15ms. - **`IPanicRollbackGuard`**: - Quản lý danh sách các vùng nhớ đã vá (`PatchRecord`). Mỗi bản vá lưu trữ: Địa chỉ đích, kích thước byte, mảng byte gốc (`OriginalBytes`), mảng byte vá (`PatchedBytes`) và mã băm kiểm tra `CRC32`. --- ## 4. Đặc Tả Chi Tiết 4 Hệ Thống Hình Ảnh (Visual Subsystems) ### 4.1. 3D Scene Camera Wheel Zoom & zFar Culling Fix - **Nguyên lý**: Camera trong Path of Exile 2 sử dụng hệ tọa độ 3D kết hợp với ma trận View/Projection. Khoảng cách mặc định bị khóa ở mức $1.0\times$ (~1200 đơn vị world space). - **Công thức tính zFar động**: $$\text{zFar}_{\text{adjusted}} = \text{zFar}_{\text{base}} \times \max\left(1.0, \frac{\text{Distance}}{\text{Distance}_{\text{base}}}\right) \times 1.25$$ - **Giải pháp triệt tiêu hiện tượng xé hình / khoảng đen**: Nếu chỉ tăng khoảng cách mà không nâng `zFar`, engine đồ họa sẽ loại bỏ (cull) toàn bộ geometry vượt quá khoảng cách cũ. Việc patch đồng bộ biến float `Camera_zFar` trong cùng struct đảm bảo toàn bộ cảnh quan 3D được hiển thị trọn vẹn. ### 4.2. Volumetric & Atlas Fog Removal - **Nguyên lý**: Game sử dụng shader tính toán sương mù dựa trên độ sâu và bản đồ thể tích (Volumetric Fog 3D Texture). - **Cơ chế can thiệp**: - Thay đổi hằng số phân rã ánh sáng của sương mù (`FogDensity` $\to 0.0f$). - Hoặc vô hiệu hóa lệnh rẽ nhánh tính toán sương mù trong shader parameter buffer (`bEnableVolumetricFog = 0`). - Giúp loại bỏ hoàn toàn các màn sương dày đặc che khuất bẫy, quái vật ẩn nấp và hiệu ứng mặt đất nguy hiểm. ### 4.3. Always-On Minimap Auto-Reveal & Triad Shader Patches Hệ thống Minimap trong PoE 2 bao gồm 3 lớp đồ họa riêng biệt: 1. **Khung dây viền xanh Cyan (`Minimap Wireframe`)**: Là một overlay quad hiển thị biên giới khu vực đã khám phá. Tiện ích áp dụng byte-patch `NOP` hoặc `RET` lên hàm vẽ khung dây, loại bỏ hoàn toàn viền cyan vướng mắt. 2. **Độ sáng Texture địa hình (`Terrain Luminance`)**: Mặc định địa hình chưa đi qua bị gán texture alpha bằng 0 hoặc tối đen. Tiện ích ghi đè hằng số ambient brightness của minimap texture buffer lên $1.0f$, hiển thị toàn cảnh địa hình sắc nét. 3. **Map Content Icons**: Kích hoạt cờ hiển thị tức thời cho các thực thể quan trọng (Strongbox, Shrine, Boss icon) mà không cần người chơi phải lại gần trong phạm vi kích hoạt thông thường. ### 4.4. In-Place Native Item Modifier Color Replacement - **Nguyên lý**: Khi render tooltip vật phẩm, engine đọc chuỗi ký tự chứa các mã điều khiển định dạng màu sắc (Color Tokens, ví dụ `^0`, `^1`, `^4`). - **Cơ chế thay thế trực tiếp**: - Thay vì can thiệp ngoài bằng overlay giả lập (dễ gây lệch tọa độ và giảm FPS), Poe2VisualTool can thiệp trực tiếp vào mảng ánh xạ `ColorTokenTable` trong bộ nhớ heap của game. - Phân tách theo 4 nhóm thuộc tính đặc thù: * **Đỏ (Physical / Attack / Dot)**: `#FF5555` * **Lam (Spell / Mana / Cast Speed)**: `#55FFFF` * **Xanh Lục / Cyan (Speed / Evasion / Resists)**: `#55FF55` * **Vàng Kim (Tier 1 High Roll / Influenced)**: `#FFAA00` - Giúp người chơi nhận diện ngay lập tức giá trị vật phẩm chỉ bằng một cái nhìn lướt qua. --- ## 5. Kênh Giao Tiếp Bộ Nhớ Chia Sẻ Lock-Free (Lock-Free Shared Memory IPC) Kênh IPC kết nối giữa C++ Core và Python Companion được thiết kế theo chuẩn **Mechanical Sympathy**, triệt tiêu toàn bộ syscall semaphore hay mutex của Windows: ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ SHARED MEMORY MAPPING: "Local\Poe2VisualTool_IPC" │ │ Kích thước: 64 KB (Căn chỉnh 64-byte Cache-Line) │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ [0x0000 - 0x0FFF] HEADER & SEQLOCK CONTROL BLOCK │ │ • Magic Number: 0x504F45325F564953 ("POE2_VIS") │ │ • Version: 0x00010000 │ │ • HeartbeatTimestamp: std::atomic (milliseconds) │ │ • SeqlockSequence: std::atomic (chẵn = ổn định, lẻ = đang ghi) │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ [0x1000 - 0x7FFF] TELEMETRY BUFFER (Seqlock Double-Buffer: Buffer A & Buffer B) │ │ • CameraState (ZoomLevel, CurrentDistance, zFarValue, FoV) │ │ • FeatureFlags (FogDisabled, MinimapRevealed, ColorizerActive) │ │ • GameProcessInfo (ProcessId, WindowRect, IsFocused) │ │ • ActivePatchesCount & Status │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ [0x8000 - 0xFFFF] COMMAND CHANNEL (SPSC Ring Buffer 16 Slots) │ │ • Head & Tail atomics (std::atomic) │ │ • CommandPackets (SetZoom, ToggleFeature, UpdateColorPalette, PanicTrigger) │ └─────────────────────────────────────────────────────────────────────────────────┘ ``` ### Thuật Toán Đọc Seqlock Phía Python (Zero-Torn-Read Protocol): ```python def read_telemetry_snapshot(shm_view): while True: seq1 = shm_view.read_uint64(SEQLOCK_OFFSET) if seq1 % 2 != 0: # Đang có ghi từ C++ Core, nhường CPU cực ngắn continue # Đọc dữ liệu telemetry từ buffer ổn định data = shm_view.read_bytes(BUFFER_OFFSET, DATA_SIZE) seq2 = shm_view.read_uint64(SEQLOCK_OFFSET) if seq1 == seq2: # Dữ liệu nguyên vẹn 100%, không bị torn-read return parse_telemetry(data) ``` --- ## 6. Cơ Chế 1-Frame Panic Restore (F12 / Pause) Khi người dùng kích hoạt Panic Restore bằng phím nóng (`Pause` hoặc `F12`): 1. **0.00ms**: Luồng Hot Path 120Hz bắt được sự kiện phím tắt trong `InputInterlock`. 2. **0.05ms**: Kích hoạt hàm `PanicRollbackGuard::ExecuteRollback()`. 3. **0.10ms - 1.50ms**: Lặp qua danh sách `std::array`: - Dùng `VirtualProtect` mở quyền `PAGE_EXECUTE_READWRITE`. - Ghi đè lại 100% `OriginalBytes` ban đầu. - Khôi phục lại cờ bảo vệ bộ nhớ nguyên thủy (`PAGE_EXECUTE_READ`). - Xóa sạch cache chỉ lệnh của CPU bằng `FlushInstructionCache(hProcess, ...)`. 4. **2.00ms**: Đặt cờ `m_isCleanDetached = true` và phát thông báo xác nhận sang Shared Memory IPC. 5. **Tổng thời gian hoàn tất**: $< 2.50\text{ ms}$ (thấp hơn rất nhiều so với ngưỡng 1 khung hình 8.33ms của màn hình 120Hz). --- ## 7. Ma Trận Bất Biến Kiến Trúc (System Invariants Matrix) Mọi can thiệp mã nguồn bắt buộc phải tuân thủ nghiêm ngặt bảng bất biến dưới đây: | Mã Invariant | Tên Bất Biến | Mô Tả Quy Chuẩn | Cơ Chế Kiểm Soát | | :--- | :--- | :--- | :--- | | **`INV-VIS-01`** | **Non-Automation Contract** | Tuyệt đối không gửi input mô phỏng (mouse click/key press) phục vụ tự hành | Đánh giá kiến trúc, cấm các API `SendInput`, `mouse_event` | | **`INV-VIS-02`** | **Hot-Path Frequency** | Vòng lặp Tier 1 duy trì chu kỳ 120Hz (sai số $\le \pm 0.5\text{ms}$) | `timeBeginPeriod(1)` + `QueryPerformanceCounter` | | **`INV-VIS-03`** | **Zero Allocation** | Cấm `new`, `malloc`, `std::vector::push_back` trong vòng lặp chính | Cố định dung lượng mảng tĩnh `std::array` | | **`INV-VIS-04`** | **Memory Section Bounds** | Địa chỉ patch bắt buộc phải nằm trọn trong phân vùng hợp lệ của module game | Kiểm tra đối chiếu với PE Header `.text` / `.rdata` bounds | | **`INV-VIS-05`** | **Atomic Panic Integrity** | Dữ liệu byte gốc phải được băm CRC32 xác thực trước khi khôi phục | `assert(CRC32(OriginalBytes) == Record.Checksum)` | | **`INV-VIS-06`** | **Focus Safety Interlock** | Không nhận lệnh zoom / phím tắt khi cửa sổ game không nắm active focus | `GetForegroundWindow() == m_hPoe2Window` | --- ## 8. Quy Trình Khởi Động & Đồng Bộ Hóa (Startup & Synchronization Lifecycle) ```mermaid sequenceDiagram autonumber participant Launcher as run_tool.bat / Launcher participant ColdPath as Python Companion (Cold Path) participant HotPath as C++ Native Engine (Hot Path) participant Game as PathOfExile.exe (DirectX 12) Launcher->>ColdPath: Khởi chạy Companion (Nếu dùng GUI) ColdPath->>ColdPath: Smart 4-Tier Path Resolution Launcher->>HotPath: Khởi chạy C++23 Native Engine HotPath->>HotPath: Mở Shared Memory "Local\Poe2VisualTool_IPC" HotPath->>Game: Kiểm tra Process & Attach RPM HotPath->>Game: Boyer-Moore Sigscan lấy các con trỏ Camera / Minimap / Fog HotPath->>HotPath: Lưu trữ OriginalBytes & Tính mã băm CRC32 HotPath->>Game: Ghi nhận các bản vá Visual Patches (Camera, Fog, Shader) loop Chu kỳ 120Hz (~8.33ms) HotPath->>Game: Điều phối Zoom & duy trì trạng thái zFar HotPath->>HotPath: Cập nhật Seqlock Double-Buffer ColdPath->>HotPath: Đọc Telemetry qua Seqlock (10-30Hz) end Note over HotPath,Game: Người dùng nhấn [Pause] hoặc [F12] (Panic Trigger) HotPath->>Game: Ghi hoàn trả OriginalBytes (Thời gian < 2.5ms) HotPath->>Game: FlushInstructionCache HotPath-->>Launcher: Thoát an toàn, sạch sẽ 100% ``` --- *Tài liệu được ban hành và bảo chứng bởi Kiến trúc sư Trưởng & Sub-Agent chuyên trách Tài liệu & Kiến trúc của dự án Poe2VisualTool.*