--- doc_id: "DOC-GDD-012" title: "Kiến Trúc Hệ Thống Cốt Truyện Kẻ Hành Khất & Biên Niên Sử Lưu Đày" category: "game_design" diataxis_type: "explanation" status: "canonical" version: "2026.1" owner_role: "poe2_game_designer" last_updated: "2026-09-29" tags: ["storyline", "quest-system", "beggar-chronicle", "narrative-acts", "grimdark-arpg"] related_code: - "server/world/storyline_types.py" - "server/world/storyline_catalog.py" - "server/world/storyline_engine.py" - "server/world/quest_engine.py" - "server/world/quest_catalog.py" - "client/webapp/js/ui/story_quest_board.js" related_docs: - "docs/game_design/QUEST_SYSTEM_ARCHITECTURE.md" - "docs/game_design/NPC_SYSTEM_ARCHITECTURE.md" summary: "Kiến trúc hệ thống cốt truyện 5 Hồi kể về hành trình một kẻ hành khất vượt qua đói rét, bùn lầy, bão cát và quái thú để vươn tới ngôi vị Bá Chủ Tối Cao cõi lưu đày." --- # TÀI LIỆU KIẾN TRÚC KỸ THUẬT: HỆ THỐNG CỐT TRUYỆN KẺ HÀNH KHẤT & BIÊN NIÊN SỬ LƯU ĐÀY # ARCHITECTURAL DESIGN RECORD (ADR) & TECHNICAL SPECIFICATION 2026 # ĐỊNH HƯỚNG: GRIMDARK SAVAGE PRIMAL EXILE ARPG (100% POE2 SPIRIT) > **Trạng thái**: APPROVED & IMPLEMENTED > **Chủ quản**: [Trưởng Nhóm Thiết Kế Game](file:///c:/Projects/FreeExile/AGENTS.md) (`poe2_game_designer`), [Kiến Trúc Sư Server](file:///c:/Projects/FreeExile/AGENTS.md) (`server_systems_architect`), [Kiến Trúc Sư Tài Liệu](file:///c:/Projects/FreeExile/AGENTS.md) (`lead_documentation_architect`). > **Module liên quan**: [server/world/storyline_engine.py](file:///c:/Projects/FreeExile/server/world/storyline_engine.py), [server/world/quest_engine.py](file:///c:/Projects/FreeExile/server/world/quest_engine.py), [proto/storyline.proto](file:///c:/Projects/FreeExile/proto/storyline.proto), [client/webapp/js/ui/story_quest_board.js](file:///c:/Projects/FreeExile/client/webapp/js/ui/story_quest_board.js). --- ## 1. BỐI CẢNH NGHỆ THUẬT & CỐT TRUYỆN GỐC (ORIGINAL NARRATIVE LORE) ### 1.1. Triết Lý Nhân Vật: Kẻ Hành Khất Đáy Cùng Xã Hội (The Mendicant Exile) Khác biệt hoàn toàn với lối mòn thiếu gia tu tiên hay đệ tử chân truyền, nhân vật chính trong `FreeExile` khởi đầu từ thân phận tận cùng đau khổ: - **Xuất thân**: Bị gia tộc quyền quý kinh kỳ vu oan mưu phản, phế sạch võ công kinh mạch, lột sạch xiêm y chỉ chừa manh chiếu rách và chiếc bát vỡ, tống lên thuyền ngục đày xuống **Vùng Đất Chết (The Deadlands)**. - **Hiện thực trần trụi**: Đói khát cào ruột xé gan, tay chân ghẻ lở, lạnh buốt thấu xương bên xác tàu vỡ nát tại [Bờ Đá Tàn Xương](file:///c:/Projects/FreeExile/server/world/zone_catalog.py). Phải vót nhọn khúc củi khô làm gậy ăn mày, tranh đoạt từng miếng thịt chuột thú biến dị với bầy [Hoang Giới Thi Cẩu](file:///c:/Projects/FreeExile/server/world/quest_catalog.py) để được sống. - **Tinh thần vươn lên**: Không trông chờ thần phật cứu rỗi, mà biến nỗi căm hờn và bản năng dã thú thành sức mạnh: học đòn *Đả Cẩu Côn Cốt*, cạy tủy quái thú hấp thụ Huyết Thạch, róc giáp bọ cạp sa mạc đúc Song Binh, chém nát cự thú cổ đại và đạp bằng 6 Cổng Hư Không để trở thành **Bá Chủ Tối Cao Cõi Lưu Đày**. --- ## 2. MA TRẬN TIẾN TRÌNH 5 HỒI & 5 CẤP BẬC THĂNG HOA (THE 5 ACTS & 5 ASCENT STAGES) ```mermaid flowchart LR A["Hồi I: Đáy Vực Đói Rét
(MENDICANT)"] --> B["Hồi II: Vũng Bùn Nhục Nhã
(SCAVENGER)"] B --> C["Hồi III: Bão Cát Nung Thể
(BONE_WARRIOR)"] C --> D["Hồi IV: Trảm Sát Thú Vương
(PRIMAL_HUNTER)"] D --> E["Hồi V: Vinh Quang Đỉnh Phong
(SOVEREIGN_OUTCAST)"] ``` | Hồi (Act) | Cấp Độ | Cấp Bậc Tiến Hóa | Bối Cảnh & Khu Vực | Thử Thách & Boss Chính | Thành Quả Cốt Lõi | | :--- | :--- | :--- | :--- | :--- | :--- | | **Hồi I: Đáy Vực Đói Rét** | 1 - 10 | `MENDICANT`
*Kẻ Ăn Mày Rách Rưới* | [Bờ Đá Tàn Xương](file:///c:/Projects/FreeExile/server/world/zone_catalog.py) | Bầy Thi Cẩu đói khát & [Đao Phủ Bến Tàu](file:///c:/Projects/FreeExile/server/world/endgame_content_catalog.py) | Gậy ăn mày đả cẩu, hấp thụ viên Huyết Thạch đầu tiên vào tủy. | | **Hồi II: Vũng Bùn Nhục Nhã** | 10 - 25 | `SCAVENGER`
*Kẻ Mót Xương Bùn Độc* | [Đầm Lầy Thối Rữa](file:///c:/Projects/FreeExile/server/world/zone_catalog.py) | Đỉa độc, U Hồn Kiếm Nô, [Cổ Thi Ngàn Năm](file:///c:/Projects/FreeExile/server/world/endgame_content_catalog.py) | Đập gãy xích sắt cai ngục, róc xương cổ thi đúc giáp hộ tâm. | | **Hồi III: Bão Cát Nung Thể** | 25 - 45 | `BONE_WARRIOR`
*Cuồng Cốt Chiến Giả* | [Sa Cốt Hoang Mạc](file:///c:/Projects/FreeExile/server/world/zone_catalog.py) | Sa tặc & [Bọ Cạp Sa Cốt Khổng Lồ](file:///c:/Projects/FreeExile/server/world/endgame_content_catalog.py) | Róc mai giáp bọ cạp đúc Song Binh Cốt Đao, lập uy thủ lĩnh kẻ cùng khổ. | | **Hồi IV: Trảm Sát Thú Vương** | 45 - 65 | `PRIMAL_HUNTER`
*Thợ Săn Cự Thú Cổ Đại* | [Phế Tích Xẻ Thịt](file:///c:/Projects/FreeExile/server/world/zone_catalog.py) | [Cổ Huyết Cự Viên](file:///c:/Projects/FreeExile/server/world/endgame_content_catalog.py) & Quỷ Mãng | Trảm sát thú vương, khoác áo choàng da thú, khắc Tà Ấn Dị Biến vào xương. | | **Hồi V: Vinh Quang Đỉnh Phong** | 65 - 100+ | `SOVEREIGN_OUTCAST`
*Bá Chủ Tối Cao Cõi Lưu Đày* | Cổng Hư Không Astral Device 6 Cổng | [Chúa Tể Hoang Vực](file:///c:/Projects/FreeExile/server/world/endgame_content_catalog.py) (Quỷ Vương Thao Thiết) | Đè bẹp Chúa Tể Hoang Vực, sở hữu [Huyết Ảnh Cổ Kính](file:///c:/Projects/FreeExile/server/world/primal_stones_crafting.py), Mốc V Chí Tôn. | --- ## 3. MÔ HÌNH DỮ LIỆU & KIẾN TRÚC MÁY TRẠNG THÁI (STATE MACHINE & DATA ARCHITECTURE) Hệ thống cốt truyện được triển khai theo mô hình Server-Authoritative tam phân lập: 1. **[storyline_types.py](file:///c:/Projects/FreeExile/server/world/storyline_types.py)**: Định nghĩa immutable DTOs (`JournalEntry`, `StoryActDefinition`, `StoryCutscene`, `PlayerStoryState`). 2. **[storyline_catalog.py](file:///c:/Projects/FreeExile/server/world/storyline_catalog.py)**: Chứa 5 Acts, 15 Journal Entries ghi lại từng lời độc thoại nội tâm gai góc, xúc động của Kẻ Hành Khất và cutscenes. 3. **[storyline_engine.py](file:///c:/Projects/FreeExile/server/world/storyline_engine.py)**: Máy trạng thái quản lý mở khóa nhật ký, tự động nâng bậc Beggar Stage và thăng cấp Act khi [QuestEngine](file:///c:/Projects/FreeExile/server/world/quest_engine.py) xác thực hoàn thành nhiệm vụ. ```mermaid sequenceDiagram autonumber actor Player as Kẻ Hành Khất (Client) participant QE as QuestEngine participant SE as StorylineEngine participant UI as StoryQuestBoard (HUD) Player->>QE: Tiêu diệt mục tiêu (record_kill / record_action) QE->>QE: Kiểm tra hoàn thành objective alt Đạt toàn bộ objective QE->>SE: Broadcast on_quest_completed(player_id, quest_id) SE->>SE: Mở khóa JournalEntry tương ứng (unlocked_journal_ids) SE->>SE: Đánh giá thăng cấp BeggarAscentStage & StoryAct SE-->>QE: Trả về danh sách nhật ký mới & Cutscene kích hoạt QE-->>UI: Push QuestStorySyncNotice UI->>UI: Cập nhật Badge Giai Đoạn & Rung Haptic phản hồi end ``` --- ## 4. BẢO MẬT & ZERO-TRUST SERVER AUTHORITY - **Bất Biến Điểm Thưởng & Chống Dupe**: Toàn bộ tiến trình đọc nhật ký và mở khóa cốt truyện đều được xác thực phía máy chủ; Client chỉ có thẩm quyền gửi yêu cầu `read_journal` hoặc `accept_quest`. - **Đồng Bộ Hai Pha 2PC Với Milestone**: Mốc hoàn thành Vạn Giới (Milestones I - V) trao tặng các loại đá bản vị quý hiếm ([Huyết Hồn Thạch](file:///c:/Projects/FreeExile/server/world/primal_stones_crafting.py), [Cổ Cốt Ấn](file:///c:/Projects/FreeExile/server/world/primal_stones_crafting.py), [Huyết Ảnh Cổ Kính](file:///c:/Projects/FreeExile/server/world/primal_stones_crafting.py)) được bảo vệ bằng thuật toán `anti-double claim` ngăn chặn race conditions tuyệt đối. - **Tích Hợp HUD Đa Nền Tảng (iOS ProMotion 120Hz & PWA)**: Giao diện [story_quest_board.js](file:///c:/Projects/FreeExile/client/webapp/js/ui/story_quest_board.js) hỗ trợ phím tắt nóng `Q` / `J`, tương thích vùng Safe Area và cảm ứng ngón tay $\ge 44\text{pt}$.