# 🌑 HALLUCINATE: The Asymmetric Mind-Game

[![Unity 2022.3+](https://img.shields.io/badge/Unity-2022.3+-black?logo=unity&logoColor=white)](https://unity.com/)
[![Photon Fusion](https://img.shields.io/badge/Networking-Photon_Fusion-blue)](https://www.photonengine.com/fusion)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **"Trong bóng tối của sự ảo giác, thị giác là công cụ mạnh mẽ nhất, nhưng sự tin tưởng lại là sai lầm chết người."**

**HALLUCINATE** là một dự án game PvP không đối xứng (Asymmetric PvP) đỉnh cao, nơi người chơi bước vào một cuộc đấu trí căng thẳng trong mê cung bóng tối. Một người nắm giữ **Ánh sáng (Seeker)**, người kia điều khiển **Cạm bẫy (Trapper)**. Đây không chỉ là trò chơi trốn tìm, đây là cuộc chiến về tâm lý và khả năng đọc tình huống.

---

## 📑 Mục lục (Table of Contents)
1. [Tầm nhìn Dự án (Project Vision)](#-tầm-nhìn-dự-án-project-vision)
2. [Cơ chế Trò chơi (Core Mechanics)](#-cơ-chế-trò-chơi-core-mechanics)
3. [Kiến trúc Kỹ thuật (Technical Architecture)](#-kiến-trúc-kỹ-thuật-technical-architecture)
4. [Hệ thống Mê cung (Maze Generation)](#-hệ-thống-mê-cung-maze-generation)
5. [Đồng bộ Mạng (Networking)](#-đồng-bộ-mạng-networking)
6. [Công cụ Phát triển (Developer Tools)](#-công-cụ-phát-triển-developer-tools)
7. [Lộ trình Phát triển (Roadmap)](#-lộ-trình-phát-triển-roadmap)
8. [Cấu trúc Thư mục (Folder Structure)](#-cấu-trúc-thư-mục-folder-structure)
9. [Hướng dẫn Cài đặt (Installation)](#-hướng-dẫn-cài-đặt-installation)

---

## 👁️ Tầm nhìn Dự án (Project Vision)

![Game Concept Art](https://scove-vault.duckdns.org/files/api/preview/big/ScoveThing/New%20Picture/modeus_1.jpg?inline=true&key=1775622184946)


Dự án hướng tới việc tạo ra một trải nghiệm **"High-Stakes Hide & Seek"**. Trọng tâm không nằm ở hành động nhanh mà ở sự **kiên nhẫn** và **tính toán**.
*   **Minimalist UI:** Giảm thiểu UI để người chơi tập trung hoàn toàn vào môi trường.
*   **Spatial Audio:** Âm thanh là "bản đồ" thứ hai.
*   **Dynamic Lighting:** Ánh sáng không chỉ để nhìn, mà là công cụ để lộ diện hoặc ẩn mình.

---

## 🎮 Cơ chế Trò chơi (Core Mechanics)

### 🌓 Sự bất đối xứng (The Asymmetry)

| Chỉ số | Seeker (Người Tìm Đường) | Trapper (Kẻ Đặt Bẫy) |
| :--- | :--- | :--- |
| **Vai trò** | Chủ động di chuyển, tìm lối thoát. | Phòng thủ, đặt bẫy, chặn đường. |
| **Tầm nhìn** | Góc nhìn thứ nhất (FPS), đèn pin giới hạn. | Góc nhìn tổng thể (Top-down) hoặc Camera an ninh. |
| **Tốc độ** | Nhanh (Sprinting: 9.0m/s). | Chậm hơn nhưng có khả năng dịch chuyển. |
| **Công cụ** | Đèn pin, Dash, Parkour. | Bẫy kẹp, Bẫy âm thanh, Khóa cửa. |

### 🔄 Vòng lặp Gameplay & Kiến trúc Hệ thống (Game Loop & System Architecture)

```mermaid
graph TD
    %% Phase 1: Initialization & Synchronization
    subgraph Initialization ["1. GIAI ĐOẠN KHỞI TẠO (NET-SYNC)"]
        A[Bắt đầu Trận đấu] --> B{Photon Fusion Matchmaking}
        B --> C[Phân vai ngẫu nhiên: Seeker vs Trapper]
        C --> D[Maze Generator: Chạy đa thuật toán Prims/Wilsons]
        D --> E[Baking NavMesh & Static Colliders]
        E --> F[Character Auto-Setup: Sync Physical Bounds]
        F --> G[Spawn Players tại vị trí đối nghịch]
    end

    %% Phase 2: Core Loop (The Heart of the Game)
    subgraph Active_Round ["2. VÒNG LẶP CHIẾN ĐẤU (CORE LOOP)"]
        G --> Loop((TICK: FixedUpdateNetwork))
        
        %% Seeker Branch
        subgraph Seeker_Logic ["SEEKER (POV 1st)"]
            S1[Input: WASD / Space / Shift] --> S2[State Machine: Move/Run/Jump/Dash]
            S2 --> S3{Hành động?}
            S3 -- "Sprinting" --> S4[Phát ra tiếng động lớn - Noise Meter Up]
            S3 -- "Sneaking" --> S5[Ẩn nấp - Noise Meter Down]
            S3 -- "Flashlight" --> S6[Nhìn rõ đường - Tốn Pin - Lộ vị trí]
            
            S4 & S5 & S6 --> S_Check{Check Environment}
            S_Check -- "Dẫm bẫy" --> S_Trap[Khống chế/Lộ diện]
            S_Check -- "Gặp cửa/đèn" --> S_Interact[Interact Logic]
        end

        %% Trapper Branch
        subgraph Trapper_Logic ["TRAPPER (STRATEGY VIEW)"]
            T1[Input: Mouse / Hotkeys] --> T2[View: Map Sơ đồ nhiệt / Camera]
            T2 --> T3{Hành động?}
            T3 -- "Đặt bẫy" --> T4[Trừ tài nguyên Bẫy - Sync mạng]
            T3 -- "Pulse Scan" --> T5[Ping vị trí Seeker tạm thời]
            T3 -- "Lock Door" --> T6[Khóa đường đi Seeker]
            
            T4 & T5 & T6 --> T_Check{Theo dõi Seeker}
        end

        %% Networking Layer
        subgraph Network_Sync ["NETWORK SYNC (PHOTON FUSION)"]
            Loop --> NS1[Client-Side Prediction]
            NS1 --> NS2[Server Reconciliation]
            NS2 --> NS3[State Sync: Networked Properties]
        end
    end

    %% Phase 3: Condition & Results
    subgraph Result_Logic ["3. ĐIỀU KIỆN THẮNG & COMEBACK"]
        S_Check -- "Chạm Exit" --> Win_S[SEEKER THẮNG]
        T_Check -- "Bắt được Seeker" --> Win_T[TRAPPER THẮNG]
        Loop -- "Timer = 0" --> Win_T
        
        Win_S & Win_T --> Post_Match[Cập nhật Rank / Thống kê]
        Post_Match --> Buff{Check Chuỗi Thắng/Thua}
        Buff -- "Người thua" --> Buff_Apply[Kích hoạt Comeback Buffs cho Round sau]
        Buff_Apply --> A
    end

    %% Connections
    S_Trap -.-> T_Check : "Phát tín hiệu cảnh báo"
    S4 -.-> T2 : "Hiển thị sóng âm trên Map"
    T4 -.-> S_Check : "Tạo Collision ẩn"
    NS3 --> Loop
```

---

## 🏗️ Kiến trúc Kỹ thuật (Technical Architecture)

### 1. Advanced Player State Machine
Hệ thống điều khiển nhân vật sử dụng mô hình **Hierarchical State Machine** kết hợp với **Photon Fusion**, cho phép xử lý các trạng thái phức tạp một cách mượt mà.

![State Machine Architecture](https://via.placeholder.com/800x300/111/4FC3F7?text=Player+State+Machine+Visualization)

```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Moving: Movement Input
    Moving --> Running: Sprint Input
    Running --> Idle: Stop
    Moving --> Sneaking: Sneak Input
    
    state "Airborne Logic" as Airborne {
        Jump --> Falling
        Falling --> Grounded
    }
    
    Moving --> Jump: Jump Input
    Airborne --> Idle: Land
    
    Moving --> Dashing: Dash Input
    Dashing --> Moving: Complete
    
    Interact --> Idle: Action Key
```

### 2. Environment Scanner & Interaction
Hệ thống quét vật thể (`EnvironmentScanner.cs`) sử dụng **SphereCast** và **OverlapSphere** để phát hiện các đối tượng `IInteractable` trong phạm vi tương tác, đảm bảo tính chính xác ngay cả trong bóng tối.

---

## 🧩 Hệ thống Mê cung (Maze Generation)

Trái tim của **HALLUCINATE** là hệ thống tạo mê cung đa thuật toán, mang lại sự đa dạng vô hạn.

| Algorithm | Complexity | Description |
| :--- | :--- | :--- |
| **Prims** | O(E log V) | Tạo mê cung "dày", nhiều nhánh ngắn, lý tưởng cho việc đặt bẫy. |
| **Wilsons** | O(N) | Thuật toán ngẫu nhiên hoàn hảo, không có thiên hướng cấu trúc nhất định. |
| **Recursive** | O(N) | Tạo ra các hành lang dài và sâu, tăng áp lực cho Seeker. |
| **Crawler** | O(N) | Tạo ra các không gian mở giống hang động hơn là mê cung truyền thống. |

### Quy trình khởi tạo (Maze Generation Pipeline)
```mermaid
graph LR
    A[Initialise Map] --> B{Algorithm Selector}
    B -- Prims --> C[Compute Spanning Tree]
    B -- Wilsons --> C
    B -- Crawler --> C
    C --> D[Environment Masking]
    D --> E[Spawn Objects: Doors/Lamps]
    E --> F[Inject Traps & Exit Strategy]
```

---

## 🌐 Đồng bộ Mạng (Networking)

Sử dụng **Photon Fusion (State Sync)** với cơ chế Client-Side Prediction để đảm bảo trải nghiệm không độ trễ cho Player di chuyển.

### Network Flow Diagram
```mermaid
sequenceDiagram
    participant CP as Local Player (Input Authority)
    participant S as Server (State Authority)
    participant RP as Remote Proxy
    
    CP->>CP: Predict Movement (DeltaTime)
    CP->>S: Send NetworkInputData (Move, Rot, Sprint)
    S->>S: Validate & Execute FixedUpdateNetwork
    S-->>CP: Reconcile State (If Mispredicted)
    S-->>RP: Sync Networked Properties (Rot, State)
```

![Networking Data Flow](https://via.placeholder.com/800x200/222/FFF?text=Photon+Fusion+State+Synchronization+Diagram)

---

## ⚖️ Hệ thống Comeback (Comeback System)

Để đảm bảo tính cân bằng, người thua vòng trước sẽ nhận được các **Adaptive Buffs**:

*   **Seeker Buffs:**
    *   `Flash Vision`: Mở rộng 50% tầm nhìn đèn pin.
    *   `Trap Sense`: Hiển thị outline của bẫy trong bán kính 5m.
*   **Trapper Buffs:**
    *   `Pulse Scan`: Quét vị trí Seeker mỗi 15 giây.
    *   `Ghost Trap`: Bẫy không thể bị phát hiện bởi `Trap Sense`.

---

## 🛠️ Công cụ Phát triển (Developer Tools)

### 1. Character Auto-Setup
Công cụ `CharacterAutoSetup.cs` tự động cấu hình `CharacterController` dựa trên các chỉ số sinh học của Model (Bones):
*   **Height:** Đo từ chân đến đỉnh đầu + 12% bù trừ.
*   **Radius:** Tính dựa trên khoảng cách giữa hai xương vai (Shoulders).
*   **Step Offset:** Tự động set bằng 15% chiều cao nhân vật.

### 2. Smart Bootstrapper
Tự động chuyển scene và khởi tạo Network Runner khi nhấn Play trong Editor, giúp giảm thiểu thời gian setup khi test.

---

## 📂 Cấu trúc Thư mục (Folder Structure)

```text
E:/Learning_Progress/Projects/HALLUCINATE/
├── Assets/
│   ├── Scripts/            # Toàn bộ logic game (C#)
│   │   ├── Player Controller/ # State Machine, Movement
│   │   ├── Fusion/         # Network Spawner, Data
│   │   ├── GameSetup/      # Maze, Character AutoSetup
│   │   └── Interactables/  # Bẫy, Cửa, Đèn
│   ├── Prefabs/            # Các đối tượng được dựng sẵn
│   ├── document/           # Tài liệu thiết kế & Ảnh (MỚI)
│   └── Scenes/             # Các màn chơi và Scene Main
├── ProjectSettings/        # Cấu hình dự án (Unity)
└── README.md               # Tài liệu này
```

---

## 🚀 Lộ trình Phát triển (Roadmap)

- [x] **Phase 1: Foundation**
    - [x] Player State Machine (Idle, Move, Run, Jump).
    - [x] Maze Generation (Multi-algorithm).
    - [x] Photon Fusion Integration.
- [ ] **Phase 2: Gameplay Core**
    - [ ] Role Selection (Seeker vs Trapper).
    - [ ] Trap Placement System.
    - [ ] Sound & Visual Detection (Noise Meter).
- [ ] **Phase 3: Polishing**
    - [ ] Lobby System & Matchmaking.
    - [ ] Adaptive Buffs System.
    - [ ] UI/UX Design (Minimalist Dashboard).

---

## 🤝 Hướng dẫn Cài đặt (Installation)

1.  **Clone Repository:**
    ```bash
    git clone https://github.com/OnlyScove/HALLUCINATE.git
    ```
2.  **Unity Version:** Đảm bảo bạn sử dụng Unity **2022.3.x** trở lên.
3.  **Photon Fusion:**
    - Truy cập [Photon Dashboard](https://dashboard.photonengine.com/).
    - Tạo một AppID (Fusion).
    - Paste AppID vào `Photon/Fusion/Resources/PhotonAppSettings`.
4.  **Run:** Mở scene `Main Scene` và nhấn Play.

---

**© 2026 ONLYSCOVE STUDIOS.**
*Hallucinate is more than a game, it's a social experiment.*

---
*(Ghi chú: Các hình ảnh trong README này là placeholder. Tài liệu chi tiết hơn có thể xem tại thư mục `/document`)*