--- doc_id: "DOC-GDD-012" title: "Hệ Thống Tổ Đội 6 Người, Phân Bổ Vật Phẩm & Mạng Xã Hội Thời Gian Thực" category: "game_design" diataxis_type: "reference" status: "canonical" version: "2026.1" owner_role: "poe2_game_designer" last_updated: "2026-10-02" tags: ["party-system", "social-engine", "loot-allocation", "scaling-matrix", "poe2"] related_code: - "server/world/game_design_matrix_schema.py" - "server/world/game_design_matrix_service.py" - "proto/party.proto" - "proto/social.proto" related_docs: - "docs/game_design/GUILD_SYSTEM_AND_SHARED_STASH.md" - "docs/standards/ENGINEERING_STANDARDS_2026.md" summary: "Đặc tả kỹ thuật chuẩn Diátaxis Reference cho hệ thống Tổ Đội 6 người, công thức khuếch đại thưởng EXP/Loot, 3 chế độ phân bổ vật phẩm, và quản lý Bạn Bè/Bang Hội thời gian thực." --- # Hệ Thống Tổ Đội 6 Người, Phân Bổ Vật Phẩm & Mạng Xã Hội Thời Gian Thực Tài liệu đặc tả quy chuẩn thiết kế game (Game Design Specification) cho hệ thống **Tổ Đội (Party System)**, **Phân Bổ Vật Phẩm (Loot Allocation)**, và **Mạng Xã Hội (Social Engine)** của dự án FreeExile theo triết lý Path of Exile 2 (PoE2 Spirit). --- ## 1. Triết Lý Thiết Kế & Nguyên Tắc Vận Hành 1. **Player-Centric ARPG Sandbox**: FreeExile đặt trọng tâm vào trải nghiệm cá nhân và phối hợp nhóm nhỏ. Tổ đội hỗ trợ tối đa 6 người chơi cùng tham gia dã ngoại, phụ bản ngục tối và săn Boss. 2. **Công Bằng & Khuyến Khích Đồng Đội**: Người chơi đi chung nhận được phần thưởng khuếch đại (EXP, Item Quantity, Currency Quantity, Rarity) khi cùng chiến đấu trong phạm vi lân cận (Nearby Radius). 3. **PoE2-Style Loot Security**: Cung cấp 3 chế độ phân bổ vật phẩm nhặt đồ minh bạch do Đội Trưởng thiết lập, triệt tiêu tranh chấp đồ giá trị. 4. **Lightweight Social Engine**: Quản lý bạn bè và bang hội tinh gọn, cập nhật trạng thái thời gian thực (Online, Vùng đất, Cấp độ) phục vụ dịch chuyển tức thời và phối hợp tác chiến. --- ## 2. Ma Trận Cân Bằng Tổ Đội (Party Scaling Matrix) Toàn bộ tham số cân bằng được chuẩn hóa tại bảng SQLite `party_scaling_matrix` trong [`server/world/game_design_matrix_schema.py`](file:///c:/Projects/FreeExile/server/world/game_design_matrix_schema.py) và truy vấn qua [`GameDesignMatrixService`](file:///c:/Projects/FreeExile/server/world/game_design_matrix_service.py). ### 2.1. Bảng Chỉ Số Khuếch Đại Theo Quy Mô (Party Size 1..6) | Quy Mô (`party_size`) | Máu Quái (`hp_multiplier`) | Thưởng EXP (`exp_bonus_pct`) | Thưởng Đồ (`item_quantity`) | Thưởng Tiền (`currency_qty`) | Thưởng Hiếm (`rarity_bonus`) | Bán Kính Chia Sẻ (`nearby_radius`) | | :---: | :---: | :---: | :---: | :---: | :---: | :---: | | **1 (Solo)** | $1.00\times$ (Gốc) | $+0\%$ | $+0\%$ | $+0\%$ | $+0\%$ | 15.0m | | **2** | $1.50\times$ ($+50\%$) | $+30\%$ | $+50\%$ | $+50\%$ | $+30\%$ | 15.0m | | **3** | $2.00\times$ ($+100\%$) | $+60\%$ | $+100\%$ | $+100\%$ | $+60\%$ | 15.0m | | **4** | $2.50\times$ ($+150\%$) | $+90\%$ | $+150\%$ | $+150\%$ | $+90\%$ | 15.0m | | **5** | $3.00\times$ ($+200\%$) | $+120\%$ | $+200\%$ | $+200\%$ | $+120\%$ | 15.0m | | **6 (Tối đa)** | $3.50\times$ ($+250\%$) | $+150\%$ | $+250\%$ | $+250\%$ | $+150\%$ | 15.0m | ### 2.2. Quy Tắc Bán Kính Lân Cận (Nearby Radius Validation) - **Ngưỡng khoảng cách**: $\Delta d \le 15.0$ đơn vị thế giới (world units/meters). - **Điều kiện hợp lệ**: 1. Cùng `zone_id` (ví dụ `zone_tang_kiem_nhai`). 2. Cùng `instance_id` (cùng phân vùng thế giới/phụ bản). 3. Khoảng cách Euclidean: $\sqrt{(x_1 - x_2)^2 + (y_1 - y_2)^2} \le 15.0$. - **Hệ quả**: Thành viên đứng ngoài bán kính chia sẻ (hoặc ở bản đồ khác) không làm tăng máu quái, không nhận được EXP chia sẻ và không kích hoạt thưởng rơi đồ. ### 2.3. Công Thức Trọng Số Phân Bổ EXP Theo Cấp Độ EXP tổng sau khi nhân hệ số thưởng tổ đội được phân bổ cho từng thành viên theo trọng số luỹ thừa cấp độ: $$\text{Weight}_i = (\text{Level}_i + 10)^{2.71}$$ $$\text{EXP}_i = \text{TotalEXP} \times \frac{\text{Weight}_i}{\sum_{j \in \text{Nearby}} \text{Weight}_j}$$ --- ## 3. Chế Độ Phân Bổ Rơi Đồ (Loot Allocation Modes) Đội Trưởng có quyền lựa chọn 1 trong 3 chế độ canonical được định nghĩa trong bảng `loot_allocation_modes`: ``` +-------------------------------------------------------------------------+ | LOOT ALLOCATION MODES | +-------------------------------------------------------------------------+ | 1. PERMANENT ALLOCATION: | | - Đồ giá trị (Magic/Rare/Unique/Currency) gán độc quyền vĩnh viễn | | - Chỉ người chơi được chỉ định mới có thể nhặt | | | | 2. SHORT ALLOCATION (PoE2 Default): | | - Khóa độc quyền 5.0 giây cho người được chỉ định | | - Sau 5.0s, chuyển sang trạng thái Free-For-All cho toàn đội | | | | 3. FREE-FOR-ALL: | | - Không khóa quyền sở hữu | | - Bất kỳ thành viên nào cũng có thể nhặt ngay khi rơi | +-------------------------------------------------------------------------+ ``` --- ## 4. Hệ Thống Bạn Bè & Danh Sách Chặn (Friend & Social Engine) Quản lý mối quan hệ xã hội 2 chiều thông qua [`proto/social.proto`](file:///c:/Projects/FreeExile/proto/social.proto). ### 4.1. Vòng Đời Mối Quan Hệ (Friendship Lifecycle) ```mermaid stateDiagram-v2 [*] --> NONE NONE --> PENDING_SENT: Gửi yêu cầu kết bạn PENDING_SENT --> ACCEPTED: Đối phương đồng ý PENDING_SENT --> NONE: Đối phương từ chối / Người gửi hủy ACCEPTED --> NONE: Xóa bạn bè NONE --> BLOCKED: Chặn người chơi PENDING_SENT --> BLOCKED: Chặn người chơi ACCEPTED --> BLOCKED: Chặn người chơi BLOCKED --> NONE: Bỏ chặn ``` ### 4.2. Ràng Buộc Kỹ Thuật & Giới Hạn Nghiệp Vụ | Tham Số | Giá Trị Giới Hạn | Mục Đích Bảo Vệ | | :--- | :---: | :--- | | **Max Friends** | 100 tài khoản | Giới hạn bộ nhớ và tối ưu truy vấn SQLite | | **Max Blocked** | 100 tài khoản | Ngăn ngừa spam danh sách chặn | | **Max Pending Outgoing** | 50 lời mời | Chống spam gửi lời mời kết bạn hàng loạt | | **Friend Request Cooldown** | 3.0 giây | Rate limit chống nghẽn mạng | | **Friend Note Max Length** | 64 ký tự | Ghi chú biệt danh hoặc thông tin liên lạc | ### 4.3. Cơ Chế Chặn Hai Chiều (Bidirectional Blacklist) - Khi người chơi A chặn người chơi B: 1. Yêu cầu kết bạn đang chờ (nếu có) bị huỷ bỏ lập tức. 2. B không thể gửi lời mời kết bạn, lời mời tổ đội hoặc tin nhắn mật thư (Whisper) tới A. 3. Trạng thái Online và vị trí bản đồ của A bị ẩn hoàn toàn đối với B. 4. Hệ thống đồng bộ thời gian thực sang `ChannelManager` của Chat Microservice. --- ## 5. Tích Hợp Hội Viên Bang Hội (Guild Roster) - **Triết lý Lightweight Guild**: Bang hội không chiếm đất hay công thành, tập trung vào giao lưu, chia sẻ kinh nghiệm và Rương Bang Hội 2PC. - **Roster Presence**: Cung cấp danh sách hội viên kèm cấp bậc (`GUILD_MASTER`, `GUILD_OFFICER`, `GUILD_MEMBER`), trạng thái Online, cấp độ và bản đồ hiện diện. - **Dịch Chuyển Tức Thời**: Hội viên bang hội có thể dùng tính năng Teleport để nhảy tới vị trí của đồng môn đang ở dã ngoại (nếu không vi phạm quy tắc cách ly). --- ## 6. Sơ Đồ Trình Tự Rơi Đồ & Phân Bổ Tổ Đội ```mermaid sequenceDiagram autonumber actor P1 as Đội Trưởng (P1) actor P2 as Thành Viên (P2) participant CE as CombatEngine participant PS as PartyService participant LS as LootDropService participant DB as GameDesignMatrix P1->>PS: set_loot_allocation(SHORT) PS->>DB: get_loot_allocation_mode("SHORT") DB-->>PS: timeout_seconds = 5.0s Note over P1,P2: Chiến đấu tiêu diệt Boss trong bán kính 15m CE->>PS: get_nearby_members(P1, radius=15.0) PS-->>CE: [P1, P2] (nearby_count = 2) CE->>DB: get_party_scaling(2) DB-->>CE: HP 1.5x, EXP +30%, Loot Qty +50%, Rarity +30% CE->>LS: spawn_loot(allocation=SHORT, assigned_to=P2) LS-->>P2: Item rơi (Hiển thị tên P2, khóa 5.0s) LS-->>P1: Item rơi (Hiển thị mờ, khóa nhặt) Note over LS: Sau 5.0 giây đếm ngược LS-->>P1: Mở khóa Free-For-All (P1 hoặc P2 đều nhặt được) ``` --- ## 7. Tra Cứu Protocol Buffers - [`proto/party.proto`](file:///c:/Projects/FreeExile/proto/party.proto): Định nghĩa thông điệp tạo nhóm, mời đội, giải tán, đồng bộ 30Hz vị trí, và cấu hình phân bổ rơi đồ. - [`proto/social.proto`](file:///c:/Projects/FreeExile/proto/social.proto): Định nghĩa thông điệp kết bạn, duyệt/từ chối, ghi chú bạn bè, danh sách chặn và danh sách hội viên bang hội.