# TÀI LIỆU THIẾT KẾ TRIỂN KHAI: HỆ THỐNG DEDICATED SKILL ENGINE ĐA NĂNG, THÍCH ỨNG LINH HOẠT VÀ TƯƠNG TÁC ĐA CHIỀU (POE2 COMPOSABLE COMBAT ARCHITECTURE)
> **Mã tài liệu**: `ARCH-SKILL-ENGINE-FLEXIBLE-2026-P6`  
> **Mốc thời gian**: 12/09/2026  
> **Trạng thái**: [ACTIVE / CORE ARCHITECTURAL BLUEPRINT]  
> **Phạm vi**: Tier 1 C++23 Core Engine (Hot Path 120Hz) & Tier 2 Python 3.11 Companion HUD  
> **Mục tiêu cốt lõi**: Triệt tiêu hoàn toàn mã cứng (Zero Hardcoding), hỗ trợ đổi build tức thì, tương tác chéo giữa các kỹ năng, trang bị nhân vật (Item Affixes/Uniques) và Auras/Buffs của đồng đội/minions.

---

## 1. TẦM NHÌN KIẾN TRÚC & NGUYÊN TẮC CỐT LÕI (FIRST PRINCIPLES)

### 1.1. Bài toán thực tế trong Path of Exile 2
Trong Path of Exile 2, hệ thống chiến đấu biến động liên tục:
- **Tần suất đổi build và trang bị cực cao**: Người chơi thường xuyên thay đổi đá kỹ năng (Gems), hoán đổi vũ khí (Weapon Swap), thay thế trang bị Unique (ví dụ: găng tay đổi cơ chế Charge, nhẫn kích hoạt bùa khi dùng kỹ năng, giáp chuyển đổi sát thương), hoặc điều chỉnh cây Thăng hoa/Nội tại.
- **Sự nguy hiểm của mã nguồn cứng nhắc (The Fragility of Hardcoding)**: Nếu viết mã C++ cứng nhắc cho riêng một build (ví dụ: gán cứng phím `Q` tích điểm cho `R`, gán cứng `T` nạp 30 Rage), thì ngay khi người chơi thay một viên Gem hoặc đổi sang class khác (Warrior, Mercenary, Sorceress, Ranger, Witch...), toàn bộ hệ thống bot sẽ:
  1. Gửi lệnh phím sai lệch, spam vào chiêu đang hồi hoặc không tồn tại.
  2. Bị nuốt lệnh do vi phạm điều kiện thi triển (Dropped inputs).
  3. Treo logic FSM, dẫn tới crash hệ thống hoặc đứng im chịu chết trong map.
- **Tương tác chéo phức tạp (Cross-Domain Interactions)**: Một chiêu thức không hoạt động cô lập, mà chịu ảnh hưởng đa chiều từ:
  - *Hiệu ứng trang bị*: Modifiers trên đồ thay đổi Animation Speed, Cooldown Recovery, Mana Cost, hoặc thêm thuộc tính đặc biệt (Trigger on Crit, Extra Damage vs Marked targets).
  - *Auras & Buffs từ Đồng đội / Minions*: Auras chia sẻ trong Party (Determination, Grace, Haste, Purity) thay đổi ngưỡng an toàn sinh tồn và tốc độ tung chiêu.
  - *Cộng hưởng giữa các kỹ năng (Skill Synergy / Priming & Detonation)*: Skill này tạo tiền đề (Priming - bùa chú, lôi điện, chuông, cọc bẫy, vũng băng) để Skill kia kích nổ (Detonation).

### 1.2. Ba nguyên tắc thiết kế bất biến (Architectural Invariants)
1. **INV-FLEX-01 (Zero-Hardcode Rule Engine)**: Toàn bộ danh mục kỹ năng, điều kiện kích hoạt, tổ hợp combo, cự ly và ngưỡng tài nguyên phải là **Data-Driven (hướng dữ liệu)** 100%, được định nghĩa qua cấu hình mở Declarative DSL (TOML/JSON), nạp động không cần biên dịch lại C++ Core.
2. **INV-FLEX-02 (Lockless Hot-Reload & Fail-Safe Degradation)**: Cho phép chuyển đổi cấu hình build tức thời ngay trong lúc bot đang chạy (Dual-buffer Atomic Swapping). Nếu cấu hình gặp lỗi cú pháp hoặc thiếu dữ liệu, hệ thống tự động suy thoái (degrade) về chế độ tự vệ an toàn (Safe Basic Combat / Mobility) thay vì sập hệ thống.
3. **INV-FLEX-03 (Composable Context & Cross-Interaction Matrix)**: Mọi quyết định xuất chiêu đều dựa trên một ngữ cảnh hợp nhất (`CombatContext`) tổng hợp đầy đủ: Trạng thái bản thân, Thuộc tính trang bị, Trạng thái mục tiêu, Hiệu ứng đồng đội và Môi trường vật lý xung quanh.

---

## 2. SƠ ĐỒ PHÂN TẦNG KIẾN TRÚC TỔNG THỂ (MULTI-TIER PIPELINE)

```mermaid
flowchart TD
    subgraph SENSORS ["1. TẦNG THU THẬP NGỮ CẢNH (REALTIME SENSORS - 120Hz)"]
        Vitals[Vitals & Resources: ES, Life, Ward, Mana, Spirit, Rage, Charges]
        Gear[Equipped Gear Modifiers & Keystone Passive Cache]
        Buffs[Active Buffs & Ailments: Stacks, Durations, Procs]
        Party[Party & Minion Context: Auras, Totems, Meatshield Count]
        Target[Target Context: Rarity, Distance, HP, Vulnerability, Ailments]
        Anim[Animation State Machine: Idle, Windup, Active, Recovery]
    end

    subgraph CONTEXT ["2. HỢP NHẤT NGỮ CẢNH (UNIFIED COMBAT CONTEXT)"]
        CombatContext["struct CombatContext (Bộ nhớ snapshot chuẩn hóa O(1))"]
    end

    subgraph ENGINE ["3. DEDICATED SKILL ENGINE (FLEXIBLE CORE)"]
        Registry["Skill & Profile Registry (Data-Driven TOML Loader)"]
        Eval["Universal Expression & Condition Evaluator (AST / Logic Gates)"]
        Synergy["Cross-Interaction & Synergy Matrix (Priming/Detonation/Affixes)"]
        Arbiter["Dynamic Priority & Posture Arbiter (Boss Rush / Clear / Kite / Support)"]
    end

    subgraph ACTUATOR ["4. TẦNG THI HÀNH & AN TOÀN PHẦN CỨNG"]
        Interlock["Focus & Safety Interlock (EnsureFocus & Pause Guard)"]
        KMBox["KMBoxNet Hardware Execution (Humanized Curves & Jitter)"]
    end

    Vitals --> CombatContext
    Gear --> CombatContext
    Buffs --> CombatContext
    Party --> CombatContext
    Target --> CombatContext
    Anim --> CombatContext

    CombatContext --> Eval
    CombatContext --> Synergy
    Registry --> Eval
    Registry --> Synergy

    Eval --> Arbiter
    Synergy --> Arbiter
    Arbiter --> Interlock
    Interlock --> KMBox
```

---

## 3. MA TRẬN TƯƠNG TÁC ĐA CHIỀU (CROSS-INTERACTION MATRIX)

Hệ thống phân rã và xử lý tương tác thành 3 trục quan hệ độc lập:

### 3.1. Trục 1: Tương tác Chéo giữa các Kỹ Năng (Skill $\leftrightarrow$ Skill Synergy)
Hệ thống áp dụng mô hình **Tag-Based Priming & Detonation Engine**:
- **Trạng thái Mồi (Priming Tags)**:
  - Một kỹ năng khi thi triển có thể gán nhãn lên mục tiêu hoặc sinh ra thực thể phụ trợ (Field Entities).
  - *Ví dụ 1*: Chiêu Leap/Pounce gán nhãn `TargetDebuff:Marked_Vulnerability` lên Boss trong $6.0\text{s}$.
  - *Ví dụ 2*: Chiêu Tempest Bell sinh ra thực thể `FieldEntity:ResonanceBell` tại tọa độ $(X, Y, Z)$ tồn tại trong $8.0\text{s}$.
  - *Ví dụ 3*: Đòn đánh liên hoàn tạo điểm tích tụ `Resource:ComboPoints` từ $1 \rightarrow 4$.
- **Kích hoạt Kích nổ (Detonation / Consumer Conditions)**:
  - Kỹ năng tiếp theo trong cây quyết định kiểm tra sự hiện diện của các Tag này:
    - Nếu mục tiêu có `TargetDebuff:Marked_Vulnerability` $\rightarrow$ Độ ưu tiên của các chiêu dồn sát thương cực đại (Burst Finisher) được tự động nhân hệ số $1.5\times$.
    - Nếu tồn tại `FieldEntity:ResonanceBell` trong cự ly $\le 250\text{u}$ $\rightarrow$ Hướng đánh của chiêu AoE/Strike tự động bẻ khóa (target-lock) vào chiếc Chuông thay vì tâm quái để tối ưu hóa sóng phản hồi.
    - Nếu `Resource:ComboPoints >= 4` $\rightarrow$ Mở khóa cờ thi triển cho kỹ năng tiêu thụ (như Bell Finisher hoặc Super Slam).

### 3.2. Trục 2: Tương tác với Thuộc Tính Trang Bị & Nội Tại (Skill $\leftrightarrow$ Gear Modifiers)
Engine định kỳ đồng bộ bảng Modifiers từ trang bị và Keystone của nhân vật vào `GearModifierCache`:
- **Chuyển đổi Tài nguyên & Cơ chế (Mechanic Override)**:
  - *Chaos Inoculation (CI)*: Tự động vô hiệu hóa kiểm tra Life, chuyển toàn bộ ngưỡng an toàn phòng thủ về Energy Shield (`SafetyThreshold = ES_Pct`).
  - *Unique Gloves (ví dụ: Way of the Stonefist / Lochtonial Caress)*: Khi phát hiện trang bị tự hoàn trả Charges (Endurance/Power/Frenzy) khi đánh trúng, Engine tự động bỏ qua các bước nạp Charge thủ công bằng chiêu phụ trợ, tăng tốc độ chu kỳ rotation.
  - *Weapon Type Constraints*: Tự động đọc loại vũ khí đang cầm (Quarterstaff, Bow, Crossbow, One-Handed Mace, Dagger, Unarmed...). Nếu người chơi đổi vũ khí trên tay (hoặc Weapon Swap phím `X`), Engine tự động kích hoạt bộ Profile tương ứng với vũ khí mới mà không bị crash hay cố tung skill của vũ khí cũ.
- **Hiệu ứng Kích hoạt Tự động (Procs & Triggers)**:
  - Nhận diện các dòng thuộc tính `Cast on Critical Strike`, `Trigger on Shock`, `Gain Rage on Hit`.
  - Khi điều kiện proc xảy ra, Engine cập nhật tức thời thời gian hồi và thời lượng buff tương ứng trong bộ nhớ.

### 3.3. Trục 3: Tương tác với Auras & Buffs của Đồng Đội / Minions (Party Synergy)
Trong môi trường tổ đội (Party Play) hoặc khi có dàn Minions / Totems triệu hồi:
- **Đọc Auras Vùng Lân Cận (Shared Auras Ingestion)**:
  - *Aura Tốc độ (Haste / Tailwind)*: Khi nhận buff tăng tốc từ đồng đội, thời gian Windup/Cast Time của các kỹ năng tự động co ngắn lại theo công thức:
    $$T_{\text{windup\_actual}} = \frac{T_{\text{base}}}{1.0 + \text{IncreasedCastSpeed}_{\text{total}}}$$
    Skill Engine tự động cập nhật thời gian chờ khóa hoạt ảnh để gửi phím tiếp theo nhanh hơn, tối đa hóa DPS.
  - *Aura Phòng thủ (Determination / Grace / Purity)*: Khi có đồng đội bảo kê tăng giáp/kháng tối đa, Engine linh hoạt nới lỏng khoảng cách giữ an toàn (Kite Distance), cho phép bot đứng áp sát gây sát thương lâu hơn.
- **Minion Meatshield Evaluation**:
  - Đếm số lượng Minions sống xung quanh (ví dụ: 5 Spirit Wolves). Nếu số lượng đệ tử $\ge 3$, bot nhận định có bức tường che chắn vật lý, giảm tần suất né đòn không cần thiết khi đánh boss.

---

## 4. NGÔN NGỮ ĐẶC TẢ CẤU HÌNH KỸ NĂNG (DECLARATIVE TABLE-DRIVEN DSL)

Toàn bộ logic chiến đấu được biểu diễn dưới dạng cấu hình **Composable TOML Profile**. Dưới đây là đặc tả chuẩn định dạng cho một Profile kỹ năng hoàn chỉnh:

```toml
# File: data/combat/profiles/monk_hollow_swirling_v2.toml
[profile_metadata]
profile_id = "monk_hollow_swirling_v2"
class_name = "Monk"
ascendancy = "MartialArtist"
primary_weapon = "Quarterstaff"
defense_type = "CI_EnergyShield"
author = "AutoPOE2 Orchestrator"
version = "2.0.0"

# ==========================================================
# 1. DANH MỤC BIẾN SỐ VÀ TRẠNG THÁI NỘI TẠI (STATE TRACKERS)
# ==========================================================
[[trackers]]
name = "combo_points"
source = "skill_hits"
max_value = 4
reset_on = ["skill_execution:tempest_bell", "combat_timeout:5000"]

[[trackers]]
name = "boss_debuff_mark"
source = "skill_debuff"
target_filter = "rarity >= 2"
duration_ms = 6000

# ==========================================================
# 2. BẢNG QUY TẮC CHIÊU THỨC (DATA-DRIVEN SKILL DEFINITIONS)
# ==========================================================

# Skill 1: Gầm nạp nộ khí trước khi giao tranh với quái lớn
[[skill]]
id = "bear_warcry"
name = "Bear Warcry"
key = "T"
kind = "combat_buff"
base_priority = 100
cooldown_ms = 8000
channel_hold_ms = 0

[skill.conditions]
target_rarity_min = 2            # Chỉ kích hoạt cho Rare (2) hoặc Unique Boss (3)
target_distance_max = 600.0       # Tầm quét phát hiện từ xa
self_rage_max = 20                # Chỉ gầm khi nộ khí hiện tại < 20 để không lãng phí
min_es_pct = 0.30                 # Ngưỡng ES tối thiểu để an toàn xuất chiêu

[skill.effects]
grant_rage = 30
grant_buff = "BearWarcryBuff"

# Skill 2: Nhảy vồ áp sát và cast bùa suy yếu lên Boss
[[skill]]
id = "wolf_leap"
name = "Wolf Leap Attack / Pounce"
key = "mouse_middle"
kind = "attack"
base_priority = 90
cooldown_ms = 3000
channel_hold_ms = 0

[skill.conditions]
target_rarity_min = 2            # Ưu tiên mục tiêu lớn
target_distance_min = 80.0        # Cự ly nhảy áp sát
target_distance_max = 450.0
require_target_not_has_debuff = "boss_debuff_mark" # Chưa dính bùa thì phải nhảy cast bùa ngay
min_es_pct = 0.50

[skill.effects]
apply_target_debuff = "boss_debuff_mark"
movement_gap_closer = true

# Skill 3: Đòn đánh liên hoàn tích lũy điểm combo
[[skill]]
id = "tempest_flurry"
name = "Tempest Flurry (Combo Builder)"
key = "Q"
kind = "attack"
base_priority = 70
cooldown_ms = 0
channel_hold_ms = 0

[skill.conditions]
target_distance_max = 180.0
tracker_max = { name = "combo_points", value = 3 } # Khi đã đủ 4 điểm thì nhường quyền cho Finisher
min_mana_pct = 0.05
min_es_pct = 0.40

[skill.effects]
increment_tracker = { name = "combo_points", amount = 1 }

# Skill 4: Kích nổ Chuông Bão khi đủ 4 Combo Points
[[skill]]
id = "tempest_bell"
name = "Tempest Bell (Resonance Finisher)"
key = "R"
kind = "attack"
base_priority = 85               # Ưu tiên cực cao khi đã đủ điều kiện
cooldown_ms = 4000
channel_hold_ms = 0

[skill.conditions]
target_distance_max = 250.0
tracker_exact = { name = "combo_points", value = 4 } # BẮT BUỘC ĐỦ 4 COMBO MỚI ĐƯỢC PHÉP CẮM BELL
min_mana_pct = 0.10
min_es_pct = 0.50

[skill.effects]
reset_tracker = "combo_points"
spawn_field_entity = { type = "ResonanceBell", duration_ms = 8000 }

# Skill 5: Xoay bão lôi diện rộng duy trì
[[skill]]
id = "charged_staff"
name = "Charged Staff / Swirling Storm"
key = "mouse_right"
kind = "attack"
base_priority = 60
cooldown_ms = 0
maintain = true                   # Giữ chuột phải để xoay bão
channel_hold_ms = 400

[skill.conditions]
target_distance_max = 220.0
close_targets_min = 1             # Có ít nhất 1 quái trong tầm xoay
min_mana_pct = 0.05
min_es_pct = 0.40

# Skill 6: Bắn ảo ảnh dọn quái rác
[[skill]]
id = "mantra_of_illusions"
name = "Mantra of Illusions"
key = "mouse_left"
kind = "attack"
base_priority = 40
cooldown_ms = 0
maintain = false

[skill.conditions]
target_distance_max = 350.0
min_mana_pct = 0.02
```

---

## 5. MÁY TRẠNG THÁI HOẠT ẢNH & CƠ CHẾ CHỐNG KẸT CHIÊU (ANIMATION LOCK FSM)

Trong C++ Core Engine, mỗi hành động được điều tiết qua một Finite State Machine (FSM) chạy với chu kỳ $8.33\text{ms}$ ($120\text{Hz}$):

```mermaid
stateDiagram-v2
    [*] --> STATE_IDLE
    
    STATE_IDLE --> STATE_WINDUP: Quyết định xuất chiêu (Key Press)
    STATE_WINDUP --> STATE_ACTIVE: Hết thời gian Windup (Hitbox active)
    STATE_ACTIVE --> STATE_RECOVERY: Sát thương phát tác
    STATE_RECOVERY --> STATE_IDLE: Hết Recovery Frames
    
    STATE_WINDUP --> STATE_EMERGENCY_CANCEL: Nguy hiểm! ES < 70% hoặc Boss Slam
    STATE_ACTIVE --> STATE_EMERGENCY_CANCEL: Nguy hiểm! ES < 70% hoặc Boss Slam
    STATE_RECOVERY --> STATE_EMERGENCY_CANCEL: Kích hoạt Dodge Roll / Leap thoát thân
    
    STATE_EMERGENCY_CANCEL --> STATE_IDLE: Hoàn tất né đòn (Invulnerable iframe)
```

### Các quy tắc vận hành FSM:
1. **Kiểm tra Non-Interruptible Invariant**: Khi nhân vật đang trong `STATE_WINDUP` của một chiêu thức không thể ngắt, Skill Engine tuyệt đối **KHÔNG gửi đè phím khác** nhằm tránh hiện tượng rớt phím trong bộ đệm hệ thống.
2. **Cơ chế Animation Recovery Cancelling**: Khi đòn đánh đã bước vào giai đoạn `STATE_RECOVERY` (sát thương đã được tính), nếu có lệnh `Dodge Roll` (Phím Space) hoặc `Wolf Leap` (MMB), Engine lập tức gửi lệnh ngắt giai đoạn chờ để nhân vật hành động ngay lập tức, gia tăng $30\%$ tốc độ phản xạ chiến đấu.
3. **Fail-Safe Watchdog (Chống Kẹt Phím)**: Nếu một chiêu thức duy trì trạng thái bận quá $1500\text{ms}$ mà không chuyển trạng thái (do lag client, mất gói tin hoặc stun bất ngờ), Watchdog sẽ tự động cưỡng chế giải phóng trạng thái về `STATE_IDLE` và nhả toàn bộ phím đang giữ.

---

## 6. CƠ CHẾ NẠP ĐỘNG & ATOMIC DUAL-BUFFER PROFILE SWAPPING

Để hỗ trợ đổi build linh hoạt mà không cần khởi động lại bot và không gây crash race-condition giữa luồng đọc RAM và luồng thi hành phím:

```cpp
// Kiến trúc Dual-Buffer Lockless Skill Profile
class SkillProfileManager {
public:
    // Đọc cấu hình từ luồng giao diện Python hoặc tệp TOML (Cold Path)
    bool LoadProfile(const std::string& tomlPath) {
        auto newProfile = std::make_shared<CombatProfile>();
        if (!ParseToml(tomlPath, *newProfile)) {
            CoreLog("[SkillEngine] Cảnh báo: Tệp cấu hình lỗi cú pháp. Tự động suy thoái về Safe Profile.");
            return false;
        }
        
        // Hoán đổi atomic con trỏ profile (Lockless RCU pattern)
        std::atomic_store_explicit(&m_activeProfile, newProfile, std::memory_order_release);
        CoreLog("[SkillEngine] Đã nạp thành công Profile mới: " + newProfile->metadata.profileId);
        return true;
    }

    // Tầng C++ Hot Path (120Hz) gọi liên tục để lấy profile hợp lệ
    std::shared_ptr<CombatProfile> GetActiveProfile() const {
        return std::atomic_load_explicit(&m_activeProfile, std::memory_order_acquire);
    }

private:
    std::shared_ptr<CombatProfile> m_activeProfile;
};
```

### Ưu điểm vượt trội:
- **Zero Downtime**: Người chơi đổi trang bị hoặc đổi kỹ năng trong game, chỉ cần chọn Profile tương ứng trên Control Center hoặc sửa file TOML, C++ Core tự động cập nhật ngay tại tick kế tiếp.
- **Thread Safety 100%**: Luồng Hot Path $120\text{Hz}$ không bao giờ bị block bởi I/O đọc tệp hay parsing chuỗi.
- **Fail-Safe Fallback**: Luôn có một Profile tối thiểu (`DefaultSafeProfile`: chỉ gồm đòn đánh thường và né đòn khẩn cấp) nằm sẵn trong bộ nhớ tĩnh để dự phòng nếu cấu hình người dùng cung cấp bị lỗi.

---

## 7. KẾ HOẠCH TRIỂN KHAI MÃ NGUỒN (ROADMAP THỰC THI)

### Giai đoạn 1: Khung Dữ Liệu & AST Condition Parser (Core Foundation)
- Hiện thực hóa lớp `SkillDefinition`, `ConditionNode`, `SkillProfile` trong thư mục `src/core/combat/`.
- Xây dựng bộ phân giải `UniversalExpressionEvaluator` hỗ trợ các phép so sánh số học và logic (`>`, `<`, `==`, `AND`, `OR`, `NOT`).

### Giai đoạn 2: Tích hợp Ngữ cảnh Toàn cục (`CombatContextBuilder`)
- Kết nối `PointerChainResolver` ($O(1)$ Vitals) để lấy tức thời ES, Life, Ward, Mana, Spirit.
- Kết nối `EntityTaxonomy` để tự động phân loại quái vật (Normal, Magic, Rare, Unique Boss).
- Kết nối bộ đệm Buff/Debuff để cập nhật các Tag (`boss_debuff_mark`, `combo_points`, `warcry_rage`).

### Giai đoạn 3: Kết nối FSM với Phần Cứng (`KMBoxNet & Focus Guard`)
- Đồng bộ các trạng thái hoạt ảnh và khoảng thời gian trễ phím tự nhiên (Gaussian Jitter $45\text{ms} \pm 12\text{ms}$).
- Đảm bảo cơ chế ngắt chiêu khẩn cấp (Emergency Dodge Roll Cancel) hoạt động với độ trễ $0\text{ms}$ khi $\text{ES} < 70\%$.

### Giai đoạn 4: Kiểm Thử Không Hồi Quy & Cổng Đánh Giá Thực Địa
- Viết kịch bản kiểm thử độc lập `AutoPOE2_Tests` mô phỏng: Đổi build tức thời, chuyển đổi vũ khí, quái vật miễn nhiễm, và thiếu tài nguyên mana.
- Đảm bảo toàn bộ hệ thống vượt qua kiểm thử với tỷ lệ đạt tuyệt đối $100\%$ PASS.