--- doc_id: "DOC-ARCH-007" title: "Kiến Trúc Bản Đồ Thế Giới Vô Hạn & Endgame Atlas" category: "architecture" diataxis_type: "explanation" status: "canonical" version: "2026.1" owner_role: "server_systems_architect" last_updated: "2026-09-29" tags: ["endgame-atlas", "world-map", "map-instances", "dungeons"] related_code: - "server/world/endgame_atlas_engine.py" - "server/world/map_instance_system.py" related_docs: - "docs/architecture/MAP_DUNGEON_AND_SECRET_CHAMBER_ARCHITECTURE.md" summary: "Kiến trúc phân vùng instance bản đồ thế giới mở, hệ thống Tinh Đồ Vô Hạn (Endgame Atlas) và định tuyến phụ bản." --- # KIẾN TRÚC BẢN ĐỒ THẾ GIỚI VÔ HẠN & HỆ THỐNG NỘI DUNG TÀN ĐỒ (ENDGAME ATLAS & MAP CONTENT ARCHITECTURE) # DỰ ÁN FREEEXILE: GRIMDARK SAVAGE PRIMAL ARPG 2.5D > **Phòng ban phụ trách**: Trưởng Nhóm Thiết Kế Hệ Thống (`poe2_game_designer`), Kiến Trúc Sư Server (`server_systems_architect`), Kiến Trúc Sư Tài Liệu (`lead_documentation_architect`). > **Mã Kiến Trúc**: `ARCH-ENDGAME-ATLAS-2026` | **Phiên bản**: `1.0.0-RELEASE` > **Tham chiếu mã nguồn**: [endgame_types.py](file:///c:/Projects/FreeExile/server/world/endgame_types.py), [endgame_content_catalog.py](file:///c:/Projects/FreeExile/server/world/endgame_content_catalog.py), [endgame_atlas_engine.py](file:///c:/Projects/FreeExile/server/world/endgame_atlas_engine.py). --- ## 1. TỔNG QUAN & ĐIỀU KIỆN CHUYỂN GIAO END-GAME (TRANSITION PROTOCOL) Khi người chơi hoàn thành chuỗi nhiệm vụ cơ bản của cốt truyện lưu đày ([quest_catalog.py](file:///c:/Projects/FreeExile/server/world/quest_catalog.py#L138-L165)), máy chủ có thẩm quyền tuyệt đối (Zero-Trust Server Authority) tự động kích hoạt trạng thái **Giai Đoạn Hậu Kỳ (Endgame Phase)**: ```mermaid flowchart TD A["Hành Trình Chiến Dịch (Campaign - 10 Canonical Zones)"] --> B{"Hoàn Thành Nhiệm Vụ Cơ Bản / Level >= 10"} B -- "Chưa Đạt" --> A B -- "Đạt Chuẩn (Eligible)" --> C["Kích Hoạt Giai Đoạn Hậu Kỳ (EndGamePhase)"] C --> D["Mở Khóa: Vô Tận Tàn Đồ Ma Vực (The Savage Infinite Atlas)"] C --> E["Khởi Động: Bàn Kích Hoạt Tàn Đồ 6 Cổng (Hideout Map Device)"] D --> F["Khám Phá Đồ Thị Node Phân Nhánh Vô Tận"] F --> G["Kích Hoạt Map: Random 1-5 Savage Map Contents"] ``` ### Tiêu Chí Thẩm Định Chuyển Giao: 1. **Nhiệm vụ quyết định**: Hoàn tất `quest_norm_05_khai_mo_van_gioi_cac` (Khai thông giao dịch Chợ Đen Lưu Đày) hoặc hạ gục Boss tại `zone_boundless_celestial_palace`. 2. **Cấp độ tối thiểu**: Level 10 (khởi đầu) lên đến Level 68+ khi bước vào bản đồ Tier 1. 3. **Mã trạng thái**: Chuyển đổi từ `EndGameStatus.LOCKED` $\to$ `ELIGIBLE` $\to$ `UNLOCKED`. --- ## 2. THUẬT TOÁN ĐỒ THỊ BẢN ĐỒ VÔ HẠN (INFINITE PROCEDURAL NODE GRAPH) Khác với các hệ thống bản đồ đóng khung, **Vô Tận Tàn Đồ Ma Vực** được kiến tạo dựa trên mô hình **Đồ Thị Phân Nhánh Vô Cực (Infinite Procedural Directed Graph)**: ```mermaid graph LR Origin["Gốc Depth 0 (T1)
Doanh Trại Bến Tàu"] --> D1_0["Node D1_0 (T1-2)
Bờ Đá Tàn Xương"] Origin --> D1_1["Node D1_1 (T1-2)
Đầm Lầy Thối Rữa"] Origin --> D1_2["Node D1_2 (T1-2)
Sa Cốt Hoang Mạc"] D1_0 --> D2_0["Node D2_0 (T2-3)
Phế Tích Xẻ Thịt"] D1_0 --> D2_1["Node D2_1 (T2-3)
Tế Đàn Man Hoang"] D1_1 --> D2_2["Node D2_2 (T2-3)
Vực Đầm Băng Độc"] D2_0 --> D3_Inf["Biên Giới Vô Hạn (Depth 3..N)
Tier 4 -> Tier 16 -> Über T17+"] ``` ### Các Thông Số Cốt Lõi Của Map-Node ([endgame_types.py](file:///c:/Projects/FreeExile/server/world/endgame_types.py#L60-L100)): - **Tọa độ lưới & Tầng sâu (`depth`, `grid_x`, `grid_y`)**: Quản lý vị trí không gian 2D trên giao diện bản đồ. Càng tiến xa gốc tọa độ (`depth`), độ khó càng gia tăng. - **Bậc Cấp Bản Đồ (Tier)**: - *Sơ Cấp (White Maps)*: Tier 1 - 5 (Quái vật Lv. 68 - 72). - *Trung Cấp (Yellow Maps)*: Tier 6 - 10 (Quái vật Lv. 73 - 77). - *Cao Cấp (Red Maps)*: Tier 11 - 15 (Quái vật Lv. 78 - 82). - *Đỉnh Cao (Pinnacle Maps)*: Tier 16 (Quái vật Lv. 83). - *Tuyệt Địa Vực Thẳm (Über Depths)*: Tier 17+ (Quái vật Lv. 84 - 100). - **Trạng thái Node (`MapNodeStatus`)**: - `UNREACHABLE`: Nằm trong sương mù chưa thám hiểm. - `DISCOVERED`: Đã hiện diện trên biên giới nhưng chưa dọn sạch node cha. - `ACCESSIBLE`: Đường đi đã thông, sẵn sàng mở cổng. - `IN_PROGRESS`: Đang trong phiên chiến đấu 6 cổng. - `CLEARED`: Đã tiêu diệt Boss, trao thưởng 1 Điểm Thiên Phú Tàn Đồ (`Atlas Passive Point`) và mở khóa các node con kề cận. --- ## 3. MA TRẬN 8 CƠ CHẾ NỘI DUNG TÀN ĐỒ (SAVAGE MAP CONTENTS MATRIX) Mỗi khi một map-node được khởi tạo, hệ thống sử dụng thuật toán ngẫu nhiên có trọng số (Weighted PRNG) để sinh ngẫu nhiên số lượng nội dung: $$\text{Số lượng Content} = \text{Random}(\text{Min}_{\text{Tier}}, \text{Max}_{\text{Tier}})$$ | Tier Bản Đồ | Số Lượng Content Tối Thiểu | Số Lượng Content Tối Đa | Xác Suất Gặp Nội Dung Hiếm (Scourge / Beast) | | :--- | :--- | :--- | :--- | | **Tier 1 - 5** | 1 | 2 | $15\%$ | | **Tier 6 - 10** | 2 | 3 | $35\%$ | | **Tier 11 - 15** | 2 | 4 | $65\%$ | | **Tier 16+ (Über)** | 3 | 5 | $100\%$ | ### Danh Sách 8 Cơ Chế Nội Dung Độc Bản ([endgame_content_catalog.py](file:///c:/Projects/FreeExile/server/world/endgame_content_catalog.py#L15-L65)): ```mermaid classDiagram class ContentType { <> BLOOD_ALTAR ABYSSAL_FISSURE BONE_STRONGBOX FERAL_ESSENCE SCOURGE_INCURSION WARLORD_AMBUSH SMUGGLER_DEN BEAST_HUNT } class MapContent { +str content_id +ContentType content_type +str name +str description +int difficulty_rating +str reward_type +Tuple spawn_coord +bool is_completed } MapContent --> ContentType ``` 1. **Huyết Tế Trận (`BLOOD_ALTAR`)**: Bàn tế máu man rợ. Người chơi kích hoạt để triệu hồi 3 đợt quái hiến tế hung bạo; hạ gục để hiến tế linh hồn đổi Cổ Cốt Ấn và Huyết Hồn Thạch. 2. **Khe Nứt Hư Không (`ABYSSAL_FISSURE`)**: Vết nứt đen ngòm rạch toạc lòng đất hoang dã, bò dài giải phóng bầy bọ ăn xác và kết thúc bằng Cổ Cốt Hư Không Tháp. 3. **Hòm Xương Ma Quỷ (`BONE_STRONGBOX`)**: Rương xương bọc xích sắt rỉ yểm tà ấn. Mở rương sẽ giải phóng đàn quái tinh anh bẫy rập (đóng băng, nổ xác, mưa máu). 4. **Tàn Cốt Tinh Hoa (`FERAL_ESSENCE`)**: Quái thú cổ đại bị giam cầm trong khối huyết thạch thô. Phá vỡ phong ấn để cướp đoạt Tinh Hoa Dị Biến rèn ép thuộc tính trang bị. 5. **Thao Thiết Xâm Thực (`SCOURGE_INCURSION`)**: Cổng dị biến máu thịt mở ra trong 45 giây đếm ngược. Bước vào không gian bóng tối đẫm máu săn lùng Quỷ Vương Thao Thiết. 6. **Đột Kích Lãnh Chúa (`WARLORD_AMBUSH`)**: Đội quân lưu đày phản trắc phục kích bất ngờ với các thủ lĩnh đao phủ trang bị giáp xương đẫm máu. 7. **Bí Thất Hắc Thị (`SMUGGLER_DEN`)**: Hốc đá ngầm ẩn giấu nơi Thương Nhân Chợ Đen Lưu Đày buôn lậu phôi đồ iLvl 85+ và tiền tệ chế tác độc bản. 8. **Thần Thú Tế Đàn (`BEAST_HUNT`)**: Lần theo dấu vết máu để săn bắt Thần Thú Cổ Đại mang 4 thuộc tính dị biến man rợ, phong ấn vào bùa tế. --- ## 4. TÍCH HỢP BÀN KÍCH HOẠT TÀN ĐỒ 6 CỔNG (6-PORTAL DEVICE WORKFLOW) Mỗi lượt thám hiểm bản đồ End-game đều thông qua vòng lặp xác thực hai pha trên [hideout_engine.py](file:///c:/Projects/FreeExile/server/world/hideout_engine.py#L174-L220): ```mermaid sequenceDiagram autonumber actor Player as Kẻ Lưu Đày (Client) participant Atlas as EndGameAtlasEngine participant Hideout as HideoutEngine (Map Device) participant Server as Game Instance Cluster Player->>Atlas: activate_map_node(player_id, node_id) Atlas->>Atlas: Kiểm tra quyền ACCESSIBLE & Thuộc tính Node Atlas->>Hideout: activate_map_device(player_id, astral_map) Hideout->>Hideout: Cấu hình 6 Cổng Tế Xương (hexagonal ring) Hideout-->>Atlas: Trả về 6 Portals, instance_id Atlas-->>Player: Mở 6 Cổng Tế Xương, kèm danh sách Random Contents Player->>Server: Bước qua cổng (Tiêu hao 1/6 cổng) Server-->>Player: Chiến đấu, kích hoạt Content & Hạ gục Boss Player->>Atlas: complete_map_node(player_id, node_id) Atlas->>Atlas: Cấp 1 Điểm Atlas Passive & Mở rộng Biên Giới Vô Hạn (Expand Frontier) Atlas-->>Player: Cập nhật bản đồ thế giới mới ``` --- ## 5. THIẾT KẾ CÔNG THÁI HỌC GIAO DIỆN (UI/UX SIMULATOR) - **Modal 12: Vô Tận Tàn Đồ Ma Vực (Endgame Infinite Atlas)**: - Tích hợp trực tiếp trên WebApp Simulator tại [client/webapp/index.html](file:///c:/Projects/FreeExile/client/webapp/index.html). - Hiển thị bản đồ phân cấp trực quan: Node Origin (Depth 0), các đường dẫn liên kết dạng vector SVG, trạng thái màu sắc theo chuẩn bóng tối hoang dã. - Bảng Thông Số Chi Tiết Node (Node Inspector Drawer): Hiển thị Tên Map, Tier, Quái Vật, Affixes gia vị, và **Badge trực quan của từng Random Content** hiện diện trong map. - Phím Kích Hoạt Tàn Đồ: Đồng bộ tức thì tới Bàn Kích Hoạt Tàn Đồ tại Sào Huyệt. --- ## 6. KIỂM THỬ TỰ HÀNH & CHUẨN MỰC BẢO MẬT (TDD & AUDIT) 1. **Bộ kiểm thử đơn vị độc lập**: [test_endgame_atlas_system.py](file:///c:/Projects/FreeExile/tests/unit/test_endgame_atlas_system.py) (9/9 tests pass). 2. **Bảo toàn toàn hệ thống**: Vượt qua **230/230 test cases** toàn bộ repo. 3. **Bảo mật Server-Authoritative**: Ngăn chặn tuyệt đối hành vi can thiệp packet để kích hoạt node chưa mở đường (`UNREACHABLE`). Mọi tọa độ và tỷ lệ rớt đồ do Game Server tính toán 100%.