---
doc_id: "DOC-GDD-015"
title: "Thiết Kế Hệ Thống Ô Lưới Không Gian 2D Cho Trang Bị & Rương"
category: "game_design"
diataxis_type: "reference"
status: "canonical"
version: "2026.1"
owner_role: "poe2_game_designer"
last_updated: "2026-09-30"
tags: ["spatial-grid", "equipment-slots", "inventory-tetris", "aabb-collision", "auto-compact"]
related_code:
  - "server/inventory/spatial_inventory_grid.py"
  - "server/inventory/spatial_grid_types.py"
  - "tests/unit/test_spatial_inventory_grid.py"
related_docs:
  - "docs/game_design/INVENTORY_STASH_AND_PREMIUM_MERCHANT_SYSTEM.md"
summary: "Quy chuẩn ma trận ô lưới không gian 2D WxH cho từng dòng trang bị, thuật toán AABB va chạm, First-Fit và 2D Bin-Packing Defragmentation."
---

# FREEEXILE: THIẾT KẾ HỆ THỐNG SLOT TRANG BỊ TRONG TÚI ĐỒ & RƯƠNG (SPATIAL GRID SYSTEM)

Tài liệu đặc tả kiến trúc kỹ thuật hệ thống Ô Lưới Không Gian 2D (Spatial 2D Grid Slot System) cho Trang Bị khi nằm trong Túi Đồ Sinh Tồn (Inventory Bag), Kho Cá Nhân (Personal Stash) và Rương Bán Hàng (Premium Merchant Stash Tab) theo chuẩn hardcore ARPG (Path of Exile 2 / Diablo 2).

---

## 1. TRIẾT LÝ THIẾT KẾ: BẢN VỊ KHÔNG GIAN THỰC (POE2 SPIRIT)

Trong ARPG nguyên bản hoang dã, trang bị không phải là các icon $1 \times 1$ đồng nhất vô vị. Mỗi món trang bị mang thể tích và trọng lượng vật lý riêng biệt thể hiện qua **Hộp Chiếm Dụng Không Gian (Spatial Bounding Box: $W \times H$)**:
- Một thanh **Xích Huyết Trảm Ma Cự Kiếm** dài 2 mét nặng 80kg chiếm $2 \times 4 = 8$ ô lưới.
- Một chiếc **Hắc Ám Giới Chỉ** bằng xương quỷ chỉ chiếm $1 \times 1 = 1$ ô lưới.
- Quản lý không gian túi đồ (Inventory Tetris) là một phần cốt lõi của trải nghiệm sinh tồn, cân nhắc giá trị vật phẩm khi nhặt đồ trong hoang vực.

```mermaid
flowchart TD
    subgraph Grid["Khung Lưới Không Gian 2D (Spatial Canvas)"]
        W2H4["Cự Kiếm 2 Tay (2 x 4 Ô)"]
        W2H3["Huyết Giáp (2 x 3 Ô)"]
        W2H2["Mũ / Giày (2 x 2 Ô)"]
        W2H1["Đai Lưng (2 x 1 Ô)"]
        W1H1["Nhẫn / Đá Huyết (1 x 1 Ô)"]
    end

    Grid --> Engine["SpatialInventoryGrid Engine (server/inventory/)"]
    Engine --> Bounds["Kiểm Tra Biên (Bounds Check)"]
    Engine --> Col["Dò Va Chạm (Collision Detection)"]
    Engine --> Fit["Tìm Ô Trống (First-Fit Scan)"]
    Engine --> Defrag["Tự Động Sắp Xếp (2D Bin-Packing Defragmentation)"]
```

---

## 2. MA TRẬN KÍCH THƯỚC Ô LƯỚI CHIẾM DỤNG ($W \times H$)

Bảng quy chuẩn kích thước ô cho toàn bộ chủng loại vật phẩm trong hệ thống ([`server/inventory/spatial_grid_types.py`](file:///c:/Projects/FreeExile/server/inventory/spatial_grid_types.py)):

| Phân Loại Trang Bị | Mã Phân Loại (Subtype) | Kích Thước ($W \times H$) | Tổng Số Ô | Đại Diện Điển Hình |
| :--- | :--- | :---: | :---: | :--- |
| **Vũ Khí 2 Tay** | `WEAPON_2H` | **$2 \times 4$** | 8 ô | Xích Huyết Trảm Ma Kiếm, Thôn Cốt Long Ngạc Cự Phủ, Tích Cốt Ma Hồn Cung, Thần Phù Tế Cốt Kích, Thái Hư Hủ Hồn Ma Trượng |
| **Vũ Khí 1 Tay Dài** | `WEAPON_1H` | **$1 \times 3$** | 3 ô | Huyết Đao 1 Tay, Đao Chém Thịt, Kiếm Ngắn Man Tộc |
| **Vũ Khí 1 Tay Ngắn** | `DAGGER` | **$1 \times 2$** | 2 ô | Song Nanh Quỷ Xà Đao (Twin Fang Daggers), Trủy Thủ |
| **Khiên Hộ Thân** | `SHIELD` | **$2 \times 2$** / **$2 \times 3$** | 4-6 ô | Cốt Khiên Cự Thú, Mai Rùa Hóa Thạch |
| **Chiến Giáp Thân Thể** | `BODY_ARMOR` | **$2 \times 3$** | 6 ô | Dạ Xoa Huyết Giáp, Hắc Báo Hung Bì Giáp |
| **Nón Bảo Hộ** | `HELMET` | **$2 \times 2$** | 4 ô | Đầu Lâu Khủng Long Bọc Sắt, Mặt Nạ Tế Lễ |
| **Bao Tay Hộ Uyển** | `GLOVES` | **$2 \times 2$** | 4 ô | Hộ Uyển Da Cá Sấu Gai, Bao Tay Vuốt Hổ |
| **Hài Thân Pháp** | `BOOTS` | **$2 \times 2$** | 4 ô | Huyễn Ảnh Báo Thân Hài, Hài Xương Đầm Lầy |
| **Đai Lưng Cốt Đái** | `BELT` | **$2 \times 1$** | 2 ô | Cốt Đái Răng Nanh Cổ Thú, Đai Da Tê Giác |
| **Hộ Thân Phù** | `AMULET` | **$1 \times 1$** | 1 ô | Cốt Phù Ma Thú, Dây Chuyền Hắc Ngọc |
| **Ma Giới Chỉ** | `RING` | **$1 \times 1$** | 1 ô | Giới Chỉ Răng Quỷ, Nhẫn San Hô Huyết Tộc |
| **Đá Huyết Barter** | `CURRENCY` | **$1 \times 1$** | 1 ô | Hỗn Nguyên Thạch, Thiên Mệnh Đan, Huyết Hồn Thạch (Stack tối đa 5.000) |
| **Bình Dược Sinh Tồn** | `FLASK` | **$1 \times 2$** | 2 ô | Tù Và Huyết Tủy, Bình Độc Dịch Tê Dại |
| **Cuộn Da Dịch Chuyển** | `SCROLL` | **$1 \times 1$** | 1 ô | Cuộn Da Thú Khắc Cổ Phù |

---

## 3. THIẾT KẾ KHUNG CANVAS LƯỚI CHO TÚI & RƯƠNG

### 3.1. Túi Đồ Sinh Tồn Nhân Vật (Character Inventory Canvas)
- **Kích thước chuẩn**: **$12$ Cột $\times 5$ Hàng = $60$ ô cơ bản** (tương đương chuẩn mực PoE/PoE2).
- **Hệ trục tọa độ**: Tọa độ $(x, y)$ với $0 \le x < 12$ và $0 \le y < 5$.
- **Sức chứa linh hoạt**: Có thể chứa tối đa 7 món Vũ khí 2 tay ($2 \times 4$), hoặc 10 bộ Áo giáp ($2 \times 3$), hoặc 60 viên đá huyết $1 \times 1$.
- **Nút "Sắp Xếp Gọn" (Auto-Sort)**: Kích hoạt thuật toán 2D Bin-Packing dọn dẹp phân mảnh.

```
+---+---+---+---+---+---+---+---+---+---+---+---+
| W | W | A | A | H | H | G | G | B | B | R | R |  (Hàng 0)
| W | W | A | A | H | H | G | G | B | B | R | R |  (Hàng 1)
| W | W | A | A | F | F | D | D | S | S | . | . |  (Hàng 2)
| W | W | . | . | F | F | D | D | S | S | . | . |  (Hàng 3)
| . | . | . | . | . | . | . | . | . | . | . | . |  (Hàng 4)
+---+---+---+---+---+---+---+---+---+---+---+---+
 0   1   2   3   4   5   6   7   8   9  10  11 (Cột)
```

### 3.2. Kho Lưu Trữ Cá Nhân (Personal Stash Tabs)
1. **Tab Thông Thường (Standard Stash Tab)**:
   - Kích thước: **$12 \times 12 = 144$ ô lưới tự do**.
   - Nhận mọi loại trang bị với kích thước thực $W \times H$.
2. **Tab Siêu Rộng (Quad Stash Tab - Premium)**:
   - Kích thước: **$24 \times 24 = 576$ ô lưới mật độ cao**.
3. **Tab Chuyên Dụng Huyết Thạch (Currency Dedicated Tab)**:
   - Không dùng lưới tự do mà gồm các **Ô Cố Định Chuyên Dụng (Fixed Affinity Slots)**:
     - 14 ô cố định cho 7 loại đá Barter chính & mảnh vỡ (mỗi ô stack đến 50.000 viên).
     - 1 khay crafting $1 \times 1$ ở giữa để đặt đồ vào đập đá trực tiếp.
     - 5 ô $1 \times 1$ đa năng dự phòng.

### 3.3. Rương Bán Hàng Lưu Đày (Premium Merchant Stash Tab)
- **Kích thước**: **$12 \times 12 = 144$ ô** (hoặc $10 \times 6$ trên giao diện mobile thu gọn).
- **Cơ chế ô**:
  - Mỗi trang bị đặt vào chiếm diện tích thực tế ($2 \times 4$, $2 \times 3$, v.v.).
  - Hệ thống tự động phủ **Nhãn Giá Niêm Yết (Price Tag Badge Overlay)** ngay trên góc item (ví dụ: `🏷️ 25 Hỗn Nguyên`).
  - Toàn bộ tọa độ chiếm dụng được đồng bộ lên Hắc Thị Hoang Vực để người mua xem trước hình dáng trực quan.

---

## 4. THUẬT TOÁN LÕI LƯỚI KHÔNG GIAN (SPATIAL GRID ALGORITHMS)

Toàn bộ thuật toán được cài đặt tại [`server/inventory/spatial_inventory_grid.py`](file:///c:/Projects/FreeExile/server/inventory/spatial_inventory_grid.py):

### 4.1. Kiểm Tra Biên & Va Chạm (Bounds & Collision Check)
Một vật phẩm kích thước $(W, H)$ muốn đặt tại tọa độ $(x, y)$ phải thỏa mãn:
1. **Ranh giới hợp lệ**:
   $$x \ge 0 \quad \land \quad y \ge 0 \quad \land \quad x + W \le \text{GridWidth} \quad \land \quad y + H \le \text{GridHeight}$$
2. **Không giao nhau với item khác**:
   $$\forall (cx, cy) \in [x, x + W) \times [y, y + H): \quad \text{Cell}(cx, cy) = \emptyset \quad \lor \quad \text{Cell}(cx, cy) = \text{CurrentItemUUID}$$

### 4.2. Thuật Toán Tìm Vị Trí Trống Đầu Tiên (First-Fit Scan)
Quét tuần tự theo thứ tự ưu tiên dòng trước cột sau:
```python
def find_first_fit(self, width: int, height: int) -> Optional[Tuple[int, int]]:
    for cy in range(self.height - height + 1):
        for cx in range(self.width - width + 1):
            if self.can_place(cx, cy, width, height):
                return cx, cy
    return None
```

### 4.3. Thuật Toán Dọn Dẹp Phân Mảnh Tự Động (2D Bin-Packing Defragmentation)
Khi người chơi bấm nút `⚡ Sắp Xếp Gọn`:
1. Thu thập toàn bộ vật phẩm trong lưới.
2. Sắp xếp danh sách giảm dần theo:
   $$\text{Area} = W \times H \quad \longrightarrow \quad \text{Height} \quad \longrightarrow \quad \text{Width}$$
   *(Vũ khí 2 tay $2 \times 4 \to$ Giáp ngực $2 \times 3 \to$ Mũ/Giày $2 \times 2 \to$ Đai $2 \times 1 \to$ Ngọc $1 \times 1$)*.
3. Giải phóng toàn bộ lưới và lần lượt thả từng vật phẩm vào vị trí `find_first_fit(W, H)` đầu tiên từ góc trên-trái $(0, 0)$.

---

## 5. KHUNG TRANG BỊ TRÊN NGƯỜI (EQUIPMENT PAPERDOLL SLOTS)

Khung trang bị nhân vật gồm 10 vị trí chuyên biệt có ràng buộc tương thích:

```mermaid
flowchart TD
    subgraph Paperdoll["Khung Trang Bị Nhân Vật (Paperdoll)"]
        H["Nón Bảo Hộ (2x2)"]
        AM["Cốt Phù (1x1)"]
        W1["Tay Chính (2x4)"]
        BA["Huyết Giáp (2x3)"]
        W2["Tay Phụ (2x4 / 2x2)"]
        GL["Bao Tay (2x2)"]
        BL["Đai Lưng (2x1)"]
        BO["Hài Thân Pháp (2x2)"]
        R1["Giới Chỉ 1 (1x1)"]
        R2["Giới Chỉ 2 (1x1)"]
    end
    H --- BA --- BL --- BO
    W1 --- BA --- W2
    GL --- BA
    AM --- H
    R1 --- BL --- R2
```

- **Ràng buộc Song Thủ (2H Weapon Constraint)**:
  - Khi gắn Vũ Khí 2 Tay vào `MAIN_HAND`, ô `OFF_HAND` tự động bị khóa mờ (`is_disabled: True`).
  - Gỡ vũ khí 2 tay sẽ giải phóng lại ô `OFF_HAND`.
- **Hoán Đổi Song Binh (Weapon Swap Set)**:
  - Cung cấp cặp slot dự phòng `SWAP_MAIN_HAND` và `SWAP_OFF_HAND`.
  - Phím nóng `Tab` hoặc `X` hoán đổi tức thì trong 0 giây không tốn thời gian mở túi đồ.

---

## 6. KHẢM CỐT SOCKET & MẠCH GÂN NGŨ HÀNH (EQUIPMENT SOCKETS)

Mỗi trang bị mang trên mình hệ thống Khảm Cốt Socket trực tiếp:
- **Số lượng Socket tối đa**:
  - Vũ Khí 2 Tay & Giáp Ngực: **Tối đa 6 Sockets**.
  - Mũ, Bao Tay, Hài Thân Pháp: **Tối đa 4 Sockets**.
  - Vũ Khí 1 Tay & Khiên: **Tối đa 3 Sockets**.
  - Nhẫn & Hộ Phù: **Tối đa 1 Socket** (Nhẫn Cổ Quan / Đục Lỗ).
- **Màu Sắc Ngũ Hành**:
  - Đỏ (Hỏa / Cương Thể - Sức Mạnh)
  - Xanh Lá (Mộc / Thân Pháp - Nhanh Nhẹn)
  - Xanh Lam (Thủy / Thần Thức - Trí Tuệ)
  - Vàng (Kim / Thổ - Hộ Thể / Đa Năng)
- **Mạch Gân Liên Kết (Socket Links)**: Các socket có dây liên kết cho phép Gem Chiêu Thức hỗ trợ (Support/Mutator Gems) tăng cường uy lực cho chiêu thức chính.

---

## 7. FILE THÀNH PHẦN & TỔ CHỨC MÃ NGUỒN

- **Mô hình dữ liệu & Kích thước**: [`server/inventory/spatial_grid_types.py`](file:///c:/Projects/FreeExile/server/inventory/spatial_grid_types.py)
- **Động cơ lưới 2D & Va chạm**: [`server/inventory/spatial_inventory_grid.py`](file:///c:/Projects/FreeExile/server/inventory/spatial_inventory_grid.py)
- **Tích hợp Service Server**: [`server/inventory/inventory_service.py`](file:///c:/Projects/FreeExile/server/inventory/inventory_service.py)
- **Giao diện Client WebApp**:
  - [`client/webapp/index.html`](file:///c:/Projects/FreeExile/client/webapp/index.html): Layout Modal `#modal-inventory` & nút Auto-Sort.
  - [`client/webapp/js/ui/inventory_stash.js`](file:///c:/Projects/FreeExile/client/webapp/js/ui/inventory_stash.js): Hiển thị badge kích thước $W \times H$ và thuật toán sắp xếp nhanh.
- **Unit Test TDD**: [`tests/unit/test_spatial_inventory_grid.py`](file:///c:/Projects/FreeExile/tests/unit/test_spatial_inventory_grid.py)