---
doc_id: "DOC-ARCH-008"
title: "Dữ Liệu Bản Đồ, Sương Mù Chiến Trận & Thuật Toán Chống Bot"
category: "architecture"
diataxis_type: "explanation"
status: "canonical"
version: "2026.1"
owner_role: "server_systems_architect"
last_updated: "2026-09-29"
tags: ["map-data", "procgen", "war-fog", "anti-bot", "server-authoritative"]
related_code:
  - "server/world/procedural_map.py"
  - "server/world/war_fog.py"
related_docs:
  - "docs/security/SECURITY_ANTI_CHEAT_BOT.md"
summary: "Thuật toán ProcGen địa hình ngẫu nhiên, sương mù Server-Authoritative War-Fog triệt tiêu hoàn toàn bot maphack."
---

# FREEEXILE: KIẾN TRÚC DỮ LIỆU BẢN ĐỒ, SƯƠNG MÙ CHIẾN TRANH & CƠ CHẾ SINH NGẪU NHIÊN CHỐNG BOT (2026.1)

Tài liệu đặc tả kiến trúc kỹ thuật hệ thống dữ liệu bản đồ, sương mù chiến tranh đơn phương máy chủ (Server-Authoritative War-Fog) và thuật toán sinh ngẫu nhiên cạm bẫy vật cản nhằm triệt tiêu bot/script và hack tầm nhìn.

---

## 1. TỔNG QUAN KIẾN TRÚC & NGUYÊN TẮC THỰC THI

```mermaid
flowchart TD
    A["Cryptographic Instance Seed"] --> B["ProceduralMapEngine"]
    B --> C["BSP Room Subdivision & Caverns"]
    C --> D["Serpentine Corridors (Sinuosity >= 1.25)"]
    D --> E["Anti-Bot Dynamic Obstacle Injection"]
    E --> F["Guaranteed A* Path Verification"]
    
    G["Player Movement Update (x, y)"] --> H["WarFogEngine (Server)"]
    H --> I["Bresenham Line-of-Sight Raycast"]
    I --> J{"FogState Matrix"}
    J -->|UNEXPLORED / EXPLORED_FOGGED| K["Mask & Drop Dynamic Entities"]
    J -->|VISIBLE (In LoS)| L["Stream Entities to Client (Zero-Trust)"]
```

### Nguyên Tắc Bất Biến:
1. **Server-Authoritative Line-of-Sight (Zero-Trust Fog)**: Máy chủ nắm toàn quyền tính toán tầm nhìn. Dữ liệu quái vật, rương đồ, bẫy động nằm ngoài ô `VISIBLE` **tuyệt đối không được gửi về client**, triệt tiêu $100\%$ nguy cơ Memory Reading hack và Maphack.
2. **Anti-Linear Pathing (Sinuosity $\ge 1.25$)**: Toàn bộ đường đi giữa điểm xuất phát và Boss/Mục tiêu đều bị uốn lượn so le bởi các khối sỏi vụn (`CRUMBLED_DEBRIS`), vũng bùn (`MUD_POOL`) và cọc xương (`BONE_CLUSTER`). Triệt tiêu bot chạy vector đường thẳng.
3. **Interactive Chokepoints (Destructible Barricades)**: Các lối đi nút cổ chai bố trí rào chắn phá hủy được (`BARRICADE_WOOD_BONE`). Yêu cầu chiêu thức tấn công làm tụt HP về 0 mới mở đường đi, ngăn chặn bot click-to-move thô sơ.
4. **Deterministic Seed-Based Regeneration**: Mỗi phiên instance được gán một seed mật mã duy nhất; cùng một seed luôn cho ra cùng một cấu trúc bản đồ, hỗ trợ kiểm toán tự động.

---

## 2. MÔ HÌNH DỮ LIỆU BẢN ĐỒ (MAP DATA DOMAIN)

Hệ thống được định nghĩa tại [`server/world/map_data_types.py`](file:///c:/Projects/FreeExile/server/world/map_data_types.py) và danh mục biomes tại [`server/world/map_biome_catalog.py`](file:///c:/Projects/FreeExile/server/world/map_biome_catalog.py).

```mermaid
classDiagram
    class TileType {
        <<enumeration>>
        VOID = 0
        FLOOR = 1
        WALL = 2
        DESTRUCTIBLE_BARRICADE = 3
        MUD_POOL = 4
        SPIKE_TRAP = 5
        CRUMBLED_DEBRIS = 6
        BONE_PILE = 7
    }

    class FogState {
        <<enumeration>>
        UNEXPLORED = 0
        EXPLORED_FOGGED = 1
        VISIBLE = 2
    }

    class TileCell {
        +int x
        +int y
        +TileType tile_type
        +bool walkable
        +bool blocks_vision
        +float movement_cost
        +int current_hp
    }

    class ObstacleInstance {
        +str obstacle_id
        +int x
        +int y
        +ObstacleType obstacle_type
        +int hp
        +bool is_destroyed
        +bool blocks_movement
        +bool blocks_vision
    }

    class MapGridData {
        +int width
        +int height
        +int seed
        +str biome
        +List~List~TileCell~~ tiles
        +Dict obstacles
        +Tuple spawn_point
        +Tuple boss_point
        +is_walkable(x, y) bool
        +blocks_vision(x, y) bool
    }

    MapGridData *-- TileCell
    MapGridData *-- ObstacleInstance
```

---

## 3. DANH MỤC 5 BIOMES HOANG DÃ CỔ VÕ (GRIMDARK BIOMES)

| ID Biome | Tên Khu Vực | Địa Hình Chính | Bảng Chướng Ngại Vật | Sinuosity | Đặc Điểm Môi Trường |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `SAVAGE_MANGROVE_SWAMP` | Bãi Tha Ma Ngập Mặn | `MUD_POOL` | Đầm Lầy Tử Thi, Rào Gỗ Gai, Bẫy Gai | $\ge 1.35$ | Bùn lầy làm chậm $60\%$, rễ cây chắn tầm nhìn. |
| `CRIMSON_BLOOD_FOREST` | Rừng Gai Huyết Tộc | `FLOOR` | Bẫy Chông Gai, Cọc Xương, Rào Gỗ | $\ge 1.30$ | Gai nhọn ẩn dưới lá mục, sương máu mờ ảo. |
| `BLEACHED_BONE_CANYON` | Hẻm Núi Xương Trắng | `FLOOR` | Đá Sụp Đổ, Cọc Xương, Rào Gỗ | $\ge 1.40$ | Vách đá dựng đứng, hẻm hẹp hiểm trở. |
| `OUTCAST_MINE_SHAFTS` | Mỏ Quặng Lưu Đày | `FLOOR` | Rào Cản Gỗ, Đá Sập, Bẫy Chông | $\ge 1.45$ | Đường hầm ziczac, cọc chống sập mục nát. |
| `CORRUPTED_FIEND_RUINS` | Phế Tích Ma Thần | `FLOOR` | Đá Vỡ Vụn, Vũng Bùn, Cọc Xương | $\ge 1.38$ | Cột đá đổ nát, bẫy tà ấn và ngõ cụt phục kích. |

---

## 4. QUY TRÌNH SƯƠNG MÙ CHIẾN TRANH & LỌC ENTITY

```mermaid
sequenceDiagram
    autonumber
    actor Client as WebApp / Native iOS Client
    participant Net as Authoritative Gateway
    participant FoW as WarFogEngine
    participant World as ProceduralMapEngine

    Client->>Net: Packet: C2S_PLAYER_MOVE(player_id, new_x, new_y)
    Net->>FoW: update_visibility(player_id, new_x, new_y, radius=12)
    FoW->>FoW: Bresenham Line-of-Sight & Occlusion Check
    Note over FoW: Cập nhật FogState: VISIBLE, EXPLORED, UNEXPLORED
    Net->>FoW: filter_visible_entities(vis_state, world_entities)
    FoW-->>Net: visible_entities (Chỉ quái vật trong ô VISIBLE)
    Net->>Client: Packet: S2C_ENTITY_STREAM(visible_entities, fog_rle_delta)
    Note over Client: Client render: Quái trong sương mù bị ẩn 100%
```

### Nén Dữ Liệu Sương Mù Bằng RLE (Run-Length Encoding):
- Chuỗi biểu diễn: `"0x256,2x34,1x12,0x89"`.
- Băng thông truyền tải: $< 80\text{ bytes}$ mỗi lần người chơi di chuyển, tối ưu tuyệt đối cho mạng di động 4G/5G và quy mô $1.000.000\text{ CCU}$.

---

## 5. THIẾT KẾ CƠ CHẾ PHẢN BOT & PHẢN SCRIPT

1. **Anti-Linear Sinuosity Algorithm**:
   - Khoảng cách chim bay: $D_{\text{direct}} = \sqrt{(x_{\text{boss}} - x_{\text{spawn}})^2 + (y_{\text{boss}} - y_{\text{spawn}})^2}$.
   - Độ dài đường đi thực tế $L_{\text{path}}$ qua A* tìm đường:
   $$\text{Sinuosity} = \frac{L_{\text{path}}}{D_{\text{direct}}} \ge 1.25$$
   - Khi bot chạy theo vector trực tiếp $\vec{v} = (x_2 - x_1, y_2 - y_1)$, nó sẽ va chạm ngay vào các đống sỏi vụn (`CRUMBLED_DEBRIS`) được xếp so le hai bên thành hành lang.
2. **Dynamic Destructible Obstacles**:
   - Rào chắn gỗ bện xương (`BARRICADE_WOOD_BONE`) sở hữu $80 - 150\text{ HP}$.
   - Khi nhận sát thương từ kỹ năng người chơi qua `damage_obstacle(map_data, x, y, dmg)`:
     - $\text{HP} \le 0 \implies \text{is\_destroyed} = \text{True}$.
     - Ô gạch chuyển thành `FLOOR`, giải phóng cản trở di chuyển và tầm nhìn.
3. **Deceptive Branch Dead-Ends**:
   - Tạo ngẫu nhiên 3–6 hành lang cụt dài 4–7 ô đâm ngang từ phòng chính.
   - Bố trí bầy quái vật phục kích trong ngõ cụt. Bot thô sơ không có bản đồ trước sẽ bị dẫn dụ vào bẫy và tiêu diệt.

---

## 6. HƯỚNG DẪN KIỂM THỬ & NGHIỆM THU TDD

Toàn bộ test suite được tự động hóa tại [`tests/unit/test_war_fog_and_procedural_map.py`](file:///c:/Projects/FreeExile/tests/unit/test_war_fog_and_procedural_map.py):
- `test_canonical_grimdark_biomes_registered`: Xác thực 5 Biomes thuần phong cách Cổ Võ Hoang Dã.
- `test_guaranteed_connectivity_spawn_to_boss`: Xác thực 100% tính liên thông từ Spawn đến Boss qua A*.
- `test_anti_bot_sinuosity_path_complexity`: Kiểm chứng tỷ lệ uốn lượn $\ge 1.25$.
- `test_attack_and_destroy_barricade`: Kiểm chứng chém vỡ vật cản mở đường theo thời gian thực.
- `test_anti_maphack_entity_filtering`: Kiểm chứng triệt tiêu rò rỉ dữ liệu quái vật ngoài vùng nhìn thấy.
- `test_fog_rle_compression`: Kiểm chứng tính toàn vẹn nén và giải nén RLE.