--- doc_id: "DOC-GDD-008" title: "Kiến Trúc Mùa Giải & Rương Chỉ Rút (Remove-Only Stash)" category: "game_design" diataxis_type: "explanation" status: "canonical" version: "2026.1" owner_role: "poe2_game_designer" last_updated: "2026-09-29" tags: ["seasonal-reset", "leagues", "remove-only-stash", "economy-reset"] related_code: - "server/world/season_league_system.py" - "server/world/season_migration.py" related_docs: - "docs/game_design/GUILD_SYSTEM_AND_SHARED_STASH.md" summary: "Chu trình reset Mùa Giải Đại Nạn Hoang Vực (Clean Slate), hợp nhất rương về Cõi Bị Lãng Quên dạng Remove-Only an toàn." --- # FREEEXILE: KIẾN TRÚC MÙA GIẢI & LUÂN HỒI CHUYỂN SINH (PATH OF EXILE 2 SEASONAL RESET SPECIFICATION) > **Cương lĩnh Kỹ thuật**: Hệ thống Mùa Giải Thử Thách (Challenge Leagues) và Chuyển Sinh Vĩnh Hằng (Standard Realm Consolidation) chuẩn công nghệ Path of Exile 2 cho FreeExile MMORPG 2.5D Cổ Võ Hắc Ám. > **Nguyên tắc cốt lõi**: Khởi đầu tinh khôi (Clean Slate Economy) mỗi đợt Big Update; Hợp nhất rương không mất đồ (Remove-Only Stash Tabs); Phân vùng thực cảnh tuyệt đối (Strict Realm Isolation); Hạ tầng Game Server & Engine hỗ trợ sẵn 100%. --- ## 1. NGUYÊN LÝ THIẾT KẾ: TẠI SAO PHẢI HỌC TẬP CƠ CHẾ RESET MÙA CỦA PATH OF EXILE 2? Trong các MMORPG truyền thống (như VLTK1, MU, WoW), sự tích lũy tài sản liên tục qua nhiều năm dẫn tới **3 căn bệnh nan y hủy diệt trò chơi**: 1. **Siêu lạm phát tiền tệ & vật phẩm (Hyperinflation)**: Sau 6-12 tháng, lượng tiền vàng và trang bị tồn kho tràn ngập thị trường. Người chơi mới hoặc người chơi bình dân (casual) vĩnh viễn không thể đuổi kịp nhóm cày cuốc thâm niên. 2. **Triệt tiêu cảm giác phấn khích săn đồ (Loot Fatigue)**: Khi người chơi đã trang bị full set đồ thần thoại, mọi quái vật rơi đồ đều trở thành "rác". Vòng lặp gameplay (core game loop) mất đi phần thưởng kích thích dopamine. 3. **Rào cản gia nhập (New Player Barrier)**: Khoảng cách cấp độ, công lực và tài sản giữa cựu thủ và tân thủ trở thành hố sâu ngăn cản người chơi mới tham gia. ### Giải Pháp PoE2: Mô Hình Song Thực Cảnh (Dual-Realm Paradigm) Path of Exile 2 giải quyết triệt để 3 vấn đề trên bằng kiến trúc **Đại Nạn Hoang Vực (Savage Scourge Cycle)**: - **Cõi Bị Lãng Quên (Standard Realm - The Forsaken Realm)**: - Thế giới vĩnh cửu, **không bao giờ bị reset**. - Là nơi lưu trữ an toàn toàn bộ nhân vật, trang bị, cổ cốt huyết thạch và chiến tích của người chơi sau khi mùa giải đại nạn kết thúc. - Người chơi bận rộn, không có thời gian chạy đua mùa mới có thể tiếp tục chơi nhân vật cũ tại đây bất cứ lúc nào. - **Mùa Giải Đại Nạn (Challenge League / Mùa Đại Nạn Hoang Vực)**: - Diễn ra theo chu kỳ 3-4 tháng gắn liền với các bản **Big Update (Phiên bản lớn)**. - **Khởi đầu tinh khôi 100% (Clean Slate)**: Mọi người chơi (dù là tân thủ hay đại gia top 1 server) đều xuất phát từ **Cấp 1, 0 Cổ Cốt, 0 Trang Bị, Rương Mùa Trống Trơn, Huyết Cốt Ma Đồ reset hoàn toàn**. - **Kinh tế tinh khiết**: Thị trường Hắc Thị Hoang Vực được tái thiết từ đầu, tỷ giá Huyết Hồn Thạch cân bằng tự nhiên theo cung cầu sinh tồn. - **Cơ chế độc quyền mùa (League Mechanics)**: Mỗi mùa giới thiệu một hệ thống gameplay mới (ví dụ: *Mùa 1: Huyết Mạch Tàn Cốt*, *Mùa 2: Hỗn Độn Dị Quái*). ```mermaid flowchart TD subgraph BigUpdateCycle ["Chu Kỳ Big Update 3-4 Tháng (PoE2 Model)"] SeasonActive["🔥 Mùa Giải Đại Nạn (Challenge League)
- Khởi đầu Cấp 1, 0 Item, Rương trống
- Kinh tế tinh khôi, đua top Ladder
- Cơ chế mùa độc quyền"] SeasonFreeze["❄️ Giai Đoạn Đóng Băng (League Freeze)
- Khóa sàn Hắc Thị Hoang Vực (Outcast Vault)
- Ngừng tạo nhân vật mùa mới"] SeasonMigration["🌪️ Đại Di Cư Sinh Tồn (Migration Pipeline)
- Nhân vật chuyển hộ khẩu sang Cõi Bị Lãng Quên
- Rương đồ mùa -> Tab 'Chỉ Rút' (Remove-Only)
- Hủy & hoàn đơn chợ về rương người bán
- Snapshot Bảng Xếp Hạng (Hall of Fame)"] NewSeasonStart["✨ Khai Mở Mùa Giải Mới (Big Update vN+1)
- Mở Realm Mùa Mới
- Nền kinh tế trắng sạch hoàn toàn"] end subgraph StandardRealm ["🏛️ Cõi Bị Lãng Quên (Standard Realm - The Forsaken Realm)"] StandardChars["Nhân Vật Cũ (Giữ nguyên Cấp & Đồ)"] StandardStash["Kho Đồ Vĩnh Cửu + Các Tab [Chỉ Rút] Tích Lũy"] end SeasonActive -->|Hết chu kỳ 3-4 tháng| SeasonFreeze SeasonFreeze --> SeasonMigration SeasonMigration -->|Di cư an toàn| StandardRealm SeasonMigration -->|Khai mở vN+1| NewSeasonStart ``` --- ## 2. KIẾN TRÚC MẠNG & DỮ LIỆU GAME SERVER (SERVER REALM PARTITIONING) ### 2.1. Phân Vùng Đa Giới (Multi-Tenancy per Realm) Để đảm bảo nhân vật Standard không thể "tuồn" đồ sang Mùa Giải mới (gây lũng đoạn kinh tế), Game Server phân vùng dữ liệu nghiêm ngặt ở tầng hạ tầng: | Tầng Hệ Thống | Phân Vùng Lưu Trữ & Định Danh | Quy Tắc Bảo Vệ | | :--- | :--- | :--- | | **Edge Gateway** | `session.realm_id = "season_01_minh_nguyet"` | Handshake xác thực phiên gắn liền với `realm_id`. | | **World Instance** | `SpatialGrid(realm_id="season_01")` | Người chơi chỉ nhìn thấy và tương tác với người cùng Realm. | | **Consignment Vault** | `UniversalConsignmentVault(league_id)` | Sàn giao dịch tách biệt 100%; không thể mua chéo giữa các Realm. | | **Redis Cache** | `freeexile:{realm_id}:char:{char_id}`
`freeexile:{realm_id}:stash:{acc_id}` | Keyspace cô lập, ngăn chặn race-condition và cross-realm contamination. | | **Kafka Event Stream** | Topic: `freeexile.events.season_01`
Topic: `freeexile.events.standard` | Event sourcing độc lập cho từng mùa giải. | ### 2.2. Trạng Thái Vòng Đời Mùa Giải (Season Lifecycle State Machine) Mỗi Mùa Giải vận hành theo một State Machine 5 trạng thái bất biến: ```mermaid stateDiagram-v2 [*] --> UPCOMING : Công bố Big Update & Đếm ngược UPCOMING --> ACTIVE : Khai mở Mùa Giải (00:00 UTC) ACTIVE --> FREEZING : Hết hạn mùa (1-2h trước bảo trì) FREEZING --> MIGRATING : Kích hoạt Pipeline Chuyển Sinh MIGRATING --> ARCHIVED : Di cư hoàn tất 100% ARCHIVED --> [*] : Lưu trữ bảng vàng Hall of Fame ``` - `UPCOMING`: Client có thể tải trước tài nguyên (pre-download patch), chưa cho tạo nhân vật. - `ACTIVE`: Cho phép tạo nhân vật Cấp 1, mở toàn diện tính năng cày cuốc, săn boss, giao dịch 2PC. - `FREEZING`: Khóa niêm yết mới trên Hắc Thị Hoang Vực, khóa nạp rút, chuẩn bị hạ snapshot. - `MIGRATING`: Pipeline backend tự động quét batch: 1. Hủy toàn bộ order đang treo trên sàn Kỳ Trân Các, hoàn trả trang bị vào rương người bán. 2. Gom các Tab Rương Dùng Chung (Shared Stash Tabs) của Mùa sang Standard dưới cờ `is_remove_only = True`. 3. Cập nhật `character.league_id = "standard"` cho toàn bộ nhân vật mùa cũ. 4. Snapshot Top 100 Bảng Xếp Hạng lưu trữ vĩnh viễn vào Hall of Fame. - `ARCHIVED`: Đóng mùa cũ; khởi tạo và kích hoạt Mùa mới (`ACTIVE`). --- ## 3. CƠ CHẾ RƯƠNG ĐỒ HỢP NHẤT "CHỈ RÚT" (REMOVE-ONLY STASH TABS) Một thách thức lớn của mô hình mùa giải là: **Nếu rương của người chơi ở Mùa 1 có 5 ngăn đầy ắp, mà rương Standard cũng đang đầy 5 ngăn, làm sao để gộp mà không làm mất đồ hoặc tràn bộ nhớ?** Path of Exile 2 giải quyết bằng phát minh **Remove-Only Stash Tabs (Tab Rương Chỉ Rút)**: 1. **Chiều Rút (Withdrawal)**: Người chơi có thể tự do lấy bất kỳ món đồ nào từ Tab Chỉ Rút về Hành Trang cá nhân hoặc cất sang các tab thường của Standard. 2. **Chiều Nạp (Deposit)**: Nghiêm cấm tuyệt đối! Mọi hành vi kéo thả đồ vào Tab Chỉ Rút đều bị Game Server từ chối tức thì với mã lỗi: `ERROR_REMOVE_ONLY_TAB_READ_ONLY`. 3. **Tự Động Dọn Dẹp (Auto-Pruning)**: Khi người chơi rút đến món đồ cuối cùng khiến Tab Chỉ Rút trở nên trống rỗng (`is_empty() == True`), hệ thống tự động xóa tab này khỏi giao diện, trả lại không gian ngăn nắp cho rương Standard. ```mermaid sequenceDiagram autonumber actor Player as Người Chơi (Standard Realm) participant Client as Client Game Engine (iOS/Metal) participant Server as Game Server Authoritative participant StashDB as Shared Stash Storage Note over Player, StashDB: Người chơi mở Tab [Chỉ Rút - Mùa 1] Player->>Client: Kéo "Cổ Kiếm Trảm Yêu" vào Túi Đồ Client->>Server: WithdrawItemRequest(tab_id="ro_01", item_uuid="sword_01") Server->>StashDB: Atomic Pop Item & Update Inventory StashDB-->>Server: OK (1 món đã rút, Tab còn 0 món) Server-->>Client: WithdrawSuccessPacket Client->>Player: Hiển thị kiếm trong túi đồ Note over Client, Server: Kiểm tra điều kiện tự động xóa Tab rỗng Server->>Server: Check if tab.is_remove_only and tab.is_empty() Server->>StashDB: DeleteEmptyRemoveOnlyTab("ro_01") Server-->>Client: StashTabPrunedNotice(tab_id="ro_01") Client->>Player: Tab Chỉ Rút biến mất khỏi UI (Kho đồ gọn gàng) Note over Player, Client: Người chơi thử nhét đồ rác vào Tab Chỉ Rút Player->>Client: Kéo "Đá Cuội" thả vào Tab [Chỉ Rút] Client->>Server: DepositItemRequest(tab_id="ro_02", item_uuid="rock_01") Server-->>Client: REJECT: Cannot deposit into Remove-Only stash tab! Client->>Player: Bật cảnh báo đỏ: "Tab Chỉ Rút không cho phép gửi đồ vào!" ``` --- ## 4. CÁC BIẾN THỂ MÙA GIẢI ĐẶC THÙ (LEAGUE ARCHETYPES) Theo tiêu chuẩn PoE2, FreeExile hỗ trợ sẵn 4 phân hệ Mùa Giải: 1. **Mùa Đại Nạn Thường (Challenge League - Softcore)**: - Chế độ tiêu chuẩn, đông đảo người chơi nhất. - Khi chết chỉ mất % điểm kinh nghiệm hiện tại, hồi sinh tại tế đàn gần nhất. 2. **Tử Sinh Luân Hồi (Hardcore League - Permadeath)**: - Chế độ sinh tồn khắc nghiệt: **Mỗi nhân vật chỉ có duy nhất 1 mạng sống**. - **Cơ chế Chuyển Sinh Ngay Lập Tức**: Khi nhân vật tử trận trong trận đánh, Game Server **không xóa nhân vật vĩnh viễn**, mà tự động chuyển hộ khẩu nhân vật về **Standard Realm**: - Nhân vật không thể tiếp tục đua top tại Hardcore League. - Nhân vật được bảo toàn toàn bộ trang bị trên người tại Standard Realm để người chơi không bị sốc mất trắng công sức. 3. **Độc Hành Tu Chân (Solo Self-Found - SSF)**: - Dành cho cao thủ thích tự lực cánh sinh: **Cấm tiệt tổ đội (Party) và cấm sàn Kỳ Trân Các (Trade)**. - Hỗ trợ nút **"Tự Nguyện Nhập Thế (Opt-in Trade Migration)"**: Người chơi có thể chủ động chuyển nhân vật SSF sang Trade League cùng mùa bất kỳ lúc nào nếu cảm thấy muốn giao lưu. 4. **Vĩnh Hằng Cảnh (Standard Realm)**: - Sân chơi lưu giữ lịch sử, nơi thử nghiệm các lối build cực hạn với trang bị di sản tích lũy qua nhiều năm. --- ## 5. BẢO CHỨNG CHẤT LƯỢNG: TDD CLOSED-LOOP & VERIFICATION RESULTS Toàn bộ hệ thống Mùa Giải & Chuyển Sinh Luân Hồi đã được kiểm chứng khép kín: - **Tầng Giao Thức Protobuf**: [season.proto](file:///c:/Projects/FreeExile/proto/season.proto) chuẩn hóa định dạng thông điệp chuyển sinh, rương đồ chỉ rút và trạng thái giải đấu. - **Tầng Quản Trị Server**: [season_league_manager.py](file:///c:/Projects/FreeExile/server/world/season_league_manager.py) điều phối vòng đời, cách ly thực cảnh, xử lý Hardcore permadeath. - **Tầng Pipeline Chuyển Sinh**: [season_migration_pipeline.py](file:///c:/Projects/FreeExile/server/world/season_migration_pipeline.py) thực thi hoàn trả ký gửi chợ, gom rương chỉ rút, chuyển hộ khẩu nhân vật, lưu bảng vàng. - **Tầng Engine Client**: [SeasonLeagueManager.ts](file:///c:/Projects/FreeExile/client/src/season/SeasonLeagueManager.ts) và WebApp Simulator tại [index.html](file:///c:/Projects/FreeExile/client/webapp/index.html) hỗ trợ trực quan hóa toàn bộ chu trình. - **Kết quả Kiểm Thử Tự Hành**: - `tests/unit/test_season_league_system.py`: 7/7 tests PASS. - `tests/unit/test_season_migration_pipeline.py`: 2/2 tests PASS. - Toàn bộ test suite: **108 unit tests + 9 integration/security tests PASS 100%**.