scove/BABA_YAGA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README

Browse Source
This commit is contained in:
scove
2026-04-08 12:02:18 +07:00
parent b22e952dd9
commit 158a3038e3
1 changed files with 163 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

238
README.md
View File

@@ -1,6 +1,6 @@
# 🌑 HALLUCINATE: The Asymmetric Mind-Game
[![Unity 2022.3+](https://img.shields.io/badge/Unity-2022.3+-black?logo=unity&logoColor=white)](https://unity.com/)
[![Unity 6000.3.10f1](https://img.shields.io/badge/Unity-6000.3.10f1_LTS-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)
@@ -27,7 +27,6 @@
![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.
@@ -109,9 +108,9 @@ graph TD
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"
S_Trap -.->|Phát tín hiệu cảnh báo| T_Check
S4 -.->|Hiển thị sóng âm trên Map| T2
T4 -.->|Tạo Collision ẩn| S_Check
NS3 --> Loop
```
@@ -122,8 +121,6 @@ graph TD
### 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
@@ -163,88 +160,190 @@ Trái tim của **HALLUCINATE** là hệ thống tạo mê cung đa thuật toá
| **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]
graph TD
subgraph Grid_Logic ["1. CẤU TRÚC LỚP BẢN ĐỒ (GRID LOGIC)"]
ML[MapLocation Class: x, z] --> Map[byte[,] map: 1=Wall, 0=Corridor]
Map --> Init[InitialiseMap: Toàn bộ là Wall - byte 1]
end
subgraph Algorithm_Engine ["2. ENGINE THUẬT TOÁN (GENERATION)"]
Init --> Choice{Algorithm Selector}
Choice -- "Prims" --> P1[Tree Growth: Start at Random Cell]
P1 --> P2[Add Neighbors to Wall List]
P2 --> P3[Connect to random Tree-Cell & Carve Corridor]
Choice -- "Wilsons" --> W1[Loop-Erased Random Walk]
W1 --> W2[Walk until hit existing Tree]
W2 --> W3[Carve path into Map - byte 0]
Choice -- "Crawler" --> C1[Spawn N Crawlers at Map Center]
C1 --> C2[Random Walk & Carve 0s based on CountSquareNeighbors]
C2 --> C3[Limit by Map Width/Depth Bounds]
end
subgraph Post_Processing ["3. XỬ LÝ HẬU KỲ & MESH GEN"]
P3 & W3 & C3 --> Neighbor[Neighbor Checks: CountSquare / Diagonal Neighbors]
Neighbor --> Scale[Scaling System: WorldPos = GridPos * scale]
Scale --> Mesh[Mesh Generator: Instantiate Prefabs / Primitive Cubes]
Mesh --> Nav[NavMesh Runtime Surface Baking for Trapper AI]
end
subgraph Interaction_Injection ["4. TIÊM VẬT THỂ (INJECTION)"]
Nav --> Lamp[LampInteractable: Light Intensity & State Sync]
Nav --> Door[DoorInteractable: Physics Bounds & Animation State]
Nav --> Exit[Exit Strategy: Calc Farthest Node for Goal Spawn]
end
```
---
## 🌐 Đồ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.
Sử dụng **Photon Fusion (State Sync)** với cơ chế Client-Side Prediction để đảm bảo trải nghiệm không độ trễ.
### Network Flow Diagram
### Network Data Flow & Synchronization
```mermaid
sequenceDiagram
participant IR as InputReader (Local)
participant CP as Local Player (Input Authority)
participant S as Server (State Authority)
participant RP as Remote Proxy
participant RP as Remote Proxy (Other Clients)
Note over IR, CP: [TICK N] Thu thập Input từ Keyboard/Mouse
IR->>CP: OnMove / OnSprint / OnJump Events
CP->>CP: Đóng gói vào NetworkInputData {move, rot, sprint}
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)
Note over CP, S: [FIXED UPDATE NETWORK]
CP->>S: Send Input (Unreliable / Reliable Data)
Note right of S: Kiểm tra Logic & Thẩm quyền (Simulation)
S->>S: Apply Input to State Machine (Tick currentState)
S->>S: Tính toán Velocity & Collision (CharacterController)
S->>S: Cập nhật [Networked] properties: CamRot, StateName
S-->>CP: State Reconciliation (Nếu sai lệch vị trí > Error Threshold)
S-->>RP: State Sync: Cập nhật Position, Rotation, Animator State
Note over RP: INTERPOLATION & RENDERING
RP->>RP: Render: Cập nhật Visuals dựa trên State Sync (Smoothing)
```
![Networking Data Flow](https://via.placeholder.com/800x200/222/FFF?text=Photon+Fusion+State+Synchronization+Diagram)
---
## ⚖️ Hệ thống Comeback (Comeback System)
## 📂 Cấu trúc Thư mục Dự án (Project Folder Structure)
Để đả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)
Dự án được tổ chức theo tiêu chuẩn công nghiệp (Standard Industry Practices), tách biệt rõ ràng giữa logic Code, Assets và Configuration.
```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
├── Assets/ # Tài nguyên chính của trò chơi
│ ├── Scripts/ # Logic Code (C#) - Được module hóa cao
│ │ ├── Attributes/ # Các Custom Attributes phục vụ Inspector
│ │ ├── Camera Controller/ # Hệ thống Camera (Follow, Shake, Zoom)
│ │ ├── Debug/ # Công cụ gỡ lỗi tại Runtime
│ │ ├── Fusion/ # Logic Networking (Spawner, Data, Rpc)
│ │ │ └── BasicSpawner.cs # Khởi tạo Runner & Quản lý Session
│ │ ├── GameSetup/ # Logic khởi tạo thế giới
│ │ │ ├── Maze/ # Hệ thống tạo mê cung đa thuật toán
│ │ │ │ ├── Crawler.cs # Thuật toán Walkers ngẫu nhiên
│ │ │ │ ├── Prims.cs # Thuật toán MST (Minimal Spanning Tree)
│ │ │ │ ├── Wilsons.cs # Thuật toán Loop-Erased Walk
│ │ │ │ └── Maze.cs # Lớp cơ sở điều phối Generation
│ │ │ └── CharacterAutoSetup.cs # Tự động cấu hình CharacterController
│ │ ├── Interactables/ # Hệ thống tương tác (IInteractable)
│ │ │ ├── DoorInteractable.cs # Logic đóng/mở & Chặn đường
│ │ │ ├── LampInteractable.cs # Hệ thống ánh sáng (On/Off)
│ │ │ └── BaseInteractable.cs # Lớp trừu tượng cho mọi vật thể
│ │ ├── Interface/ # Chứa các bản thiết kế chung (IInteractable.cs)
│ │ ├── Player Controller/ # Trái tim của Gameplay - State Machine
│ │ │ ├── PlayerStateMachine.cs # Điều phối các trạng thái chính
│ │ │ ├── InputReader.cs # Xử lý Input tập trung (New Input System)
│ │ │ └── States/ # Các lớp trạng thái riêng biệt (Idle, Run, Jump, Dash...)
│ │ ├── Optimization/ # Các Script tối ưu hóa (Culling, Object Pooling)
│ │ ├── UI/ # Quản lý giao diện người dùng
│ │ └── VFX/ # Điều khiển hiệu ứng hình ảnh (Particle, Shader)
│ ├── Prefabs/ # Các đối tượng được dựng sẵn (Player, Shrine, Camera)
│ ├── document/ # Tài liệu thiết kế, sơ đồ & Ảnh Preview
│ ├── Scenes/ # Các màn chơi (Main Scene, Lobby, Test Scenes)
│ ├── Materials/ # Các vật liệu (PBR, Cell-Shading cho Anime Model)
│ ├── Models/ # Các mô hình 3D (Humanoid F/M, Anime Models)
│ ├── Animation/ # Hệ thống Animator Controllers & FBX Clips
│ ├── Photon/ # SDK Photon Fusion & Các Plugin Networking
│ ├── TextMesh Pro/ # Tài nguyên cho hệ thống Text chất lượng cao
│ └── Settings/ # Cấu hình URP, Input System & Physics
├── ProjectSettings/ # Cấu hình toàn cục của Unity Editor
│ ├── TagManager.asset # Quản lý Layer (Ground, Interactable)
│ ├── DynamicsManager.asset # Cấu hình Physics (Gravity, Collision Matrix)
│ └── MultiplayerManager.asset # Cấu hình Networking Roles & Stripping
├── Packages/ # Quản lý các Unity Package (manifest.json)
└── README.md # Tài liệu này
```
---
---
## ⚖️ Hệ thống Comeback Đa tầng (Tiered Adaptive System)
Để đảm bảo mỗi trận đấu đều kịch tính đến giây cuối cùng, HALLUCINATE áp dụng hệ thống **"Despair Mechanics"**. Người chơi có chuỗi thua càng dài sẽ nhận được quyền năng từ mê cung càng lớn, tạo ra những khoảnh khắc lật kèo kinh điển.
### 📈 Phân tầng Buff theo Chuỗi Thua (Tiered Progression)
| Chuỗi Thua | Phân tầng | Tên gọi | Quyền năng & Cơ chế |
| :--- | :--- | :--- | :--- |
| **1 Trận** | Tier 1 | *Awakening* | Chọn 1 Buff cơ bản (Tăng tốc +15% hoặc Mở rộng tầm nhìn +20%). |
| **2 Trận** | Tier 2 | *Evolution* | Nhận 1 Buff chủ động (Kỹ năng nhấn nút) + 1 Buff bị động (Nâng cấp chỉ số). |
| **3+ Trận** | Tier 3 | *Manifestation* | **Ultimate Skill:** Kỹ năng thay đổi luật chơi trong 30s. Mê cung sẽ hỗ trợ bạn trực tiếp. |
---
### 🏃 Seeker: Ý chí Sinh tồn (Survival Evolution)
Khi Seeker liên tục thất bại, các giác quan của họ sẽ tiến hóa vượt bậc để chống lại bóng tối:
* **Tier 1 - Sixth Sense (Linh cảm):** Seeker bắt đầu nghe thấy tiếng tim đập của chính mình nhanh hơn khi Trapper đang ở gần (bán kính 15m), giúp định vị mà không cần nhìn.
* **Tier 2 - Shadow Step (Bước chân hư vô):** Di chuyển hoàn toàn không gây ra tiếng động (Noise Meter = 0) trong 20 giây đầu của trận đấu. Cho phép Seeker thiết lập vị trí an toàn sớm.
* **Tier 2 - Trap Reflex (Phản xạ tột độ):** Seeker có 50% cơ hội tự động vô hiệu hóa bẫy kẹp đầu tiên dẫm phải. Nếu thành công, Seeker sẽ được tăng 50% tốc độ chạy trong 3s.
* **Tier 3 - Ultimate: Chrono Dash:** Trong 15 giây, Seeker có thể thực hiện Dash không giới hạn (No Cooldown) và trở nên miễn nhiễm với mọi loại khống chế. Lúc này, Seeker là kẻ săn lùng lối thoát.
---
### 👁️ Trapper: Quyền năng Bóng tối (Dark Rituals)
Khi Trapper để xổng mất con mồi, mê cung sẽ hiến tế sự ổn định của nó để ban cho Trapper những quyền năng thao túng cực hạn:
* **Tier 1 - Paranoia Echo (Tiếng vọng ảo giác):** Tự động tạo ra 3 nguồn âm thanh bước chân giả chạy xung quanh Seeker để gây nhiễu loạn khả năng định hướng bằng âm thanh của họ.
* **Tier 2 - Global Blackout (Bóng tối bao trùm):** Kích hoạt khiến đèn pin của Seeker bị nhiễu (Flicker) hoặc tắt hoàn toàn trong 8 giây. Đây là thời điểm vàng để Trapper thu hẹp khoảng cách.
* **Tier 2 - Ghosting (Dịch chuyển không gian):** Trapper nhận khả năng đi xuyên qua các cánh cửa đã bị khóa hoặc các bức tường mỏng (Destructible Walls) trong 15 giây.
* **Tier 3 - Ultimate: Eye of the Abyss:** Hiển thị vị trí thực của Seeker xuyên tường (Wallhack) dưới dạng bóng đen trong 20 giây. Seeker không thể trốn chạy, chỉ có thể cầu nguyện.
---
### 🧠 Logic Cân bằng & Reset (Balance Logic)
```mermaid
graph TD
Loss[Player Loses Round] --> Streak{Check Streak}
Streak -- "1 Loss" --> T1[Tier 1 Pool: Awakening]
Streak -- "2 Losses" --> T2[Tier 2 Pool: Evolution]
Streak -- "3+ Losses" --> T3[Tier 3 Pool: Manifestation]
T1 & T2 & T3 --> Selection{Random/Manual Selection}
Selection --> Apply[Apply to Next Round Only]
Apply --> Result{Outcome?}
Result -- "Win" --> Reset[Reset Streak: Remove All Buffs]
Result -- "Loss" --> Streak
```
---
## 🚀 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).
@@ -253,10 +352,6 @@ E:/Learning_Progress/Projects/HALLUCINATE/
- [ ] 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).
---
@@ -266,17 +361,10 @@ E:/Learning_Progress/Projects/HALLUCINATE/
```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.
2. **Unity Version:** Đảm bảo bạn sử dụng Unity **6000.3.10f1** (Unity 6).
3. **Photon Fusion:** AppID cấu hình tại `Photon/Fusion/Resources/PhotonAppSettings`.
---
**© 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`)*