From 7cb68fdca25a1aefa3e43a5dc1ed475ad357e5df Mon Sep 17 00:00:00 2001 From: scove Date: Wed, 8 Apr 2026 12:16:34 +0700 Subject: [PATCH] Update README --- README.md | 568 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 381 insertions(+), 187 deletions(-) diff --git a/README.md b/README.md index ed3bda1d..54b9e76a 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,9 @@ 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) +6. [Hệ thống Comeback (Comeback System)](#-hệ-thống-comeback-đa-tầng-tiered-adaptive-system) 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) +8. [Cấu trúc Thư mục (Folder Structure)](#-cấu-trúc-thư-mục-dự-án-project-folder-structure) 9. [Hướng dẫn Cài đặt (Installation)](#-hướng-dẫn-cài-đặt-installation) --- @@ -49,68 +49,82 @@ Dự án hướng tới việc tạo ra một trải nghiệm **"High-Stakes Hid ```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 + %% Định nghĩa Style cho các nhóm + classDef initStyle fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#01579b; + classDef seekerStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#e65100; + classDef trapperStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,color:#4a148c; + classDef netStyle fill:#eceff1,stroke:#263238,stroke-dasharray: 5 5,color:#263238; + classDef winStyle fill:#e8f5e9,stroke:#1b5e20,stroke-width:3px,color:#1b5e20; + classDef criticalStyle fill:#ffebee,stroke:#b71c1c,stroke-width:2px,color:#b71c1c; - %% Phase 2: Core Loop (The Heart of the Game) - subgraph Active_Round ["2. VÒNG LẶP CHIẾN ĐẤU (CORE LOOP)"] + %% Phase 1: Initialization + subgraph Initialization ["1. KHỞI TẠO HỆ THỐNG (NET-SYNC)"] + A["🚀 Bắt đầu Trận đấu"] --> B{"🤝 Matchmaking
(Photon Fusion)"} + B --> C["🎭 Phân vai: Seeker vs Trapper"] + C --> D["🧩 Maze Generator
(Prims/Wilsons)"] + D --> E["🏗️ Baking NavMesh & Colliders"] + E --> F["🧍 Character Auto-Setup"] + F --> G["📍 Spawn Players"] + end + class Initialization,A,B,C,D,E,F,G initStyle; + + %% Phase 2: Core Loop + 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í] + subgraph Seeker_Logic ["🏃 SEEKER (POV 1st)"] + S1["⌨️ Input: WASD/Space"] --> S2["🏃 State: Move/Dash"] + S2 --> S3{"⚡ Hành động?"} + S3 -- "Sprinting" --> S4["🔊 Noise Up"] + S3 -- "Sneaking" --> S5["🤫 Noise Down"] + S3 -- "Flashlight" --> S6["🔦 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] + S4 & S5 & S6 --> S_Check{"🔍 Check Env"} + S_Check -- "Dẫm bẫy" --> S_Trap["⚠️ Bị khống chế"] 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] + subgraph Trapper_Logic ["🕸️ TRAPPER (STRATEGY)"] + T1["🖱️ Mouse Input"] --> T2["🗺️ View: Heatmap/Cams"] + T2 --> T3{"🛠️ Kỹ năng?"} + T3 -- "Đặt bẫy" --> T4["🪤 Sync Trap"] + T3 -- "Scan" --> T5["📡 Ping Seeker"] + T3 -- "Lock" --> T6["🚪 Khóa cửa"] - T4 & T5 & T6 --> T_Check{Theo dõi Seeker} + T4 & T5 & T6 --> T_Check{"👁️ Theo dõi"} 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] + subgraph Network_Sync ["🌐 NETWORK SYNC"] + Loop --> NS1["⏩ Client Prediction"] + NS1 --> NS2["🔄 Server Reconciliation"] + NS2 --> NS3["📦 State Sync"] end end + class Seeker_Logic,S1,S2,S3,S4,S5,S6,S_Check seekerStyle; + class Trapper_Logic,T1,T2,T3,T4,T5,T6,T_Check trapperStyle; + class Network_Sync,NS1,NS2,NS3,Loop netStyle; + class S_Trap criticalStyle; - %% 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] + %% Phase 3: Results + subgraph Result_Logic ["3. KẾT THÚC & THƯỞNG"] + 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] + Win_S & Win_T --> Post_Match["📊 Thống kê Rank"] + Post_Match --> Buff{"⚖️ Balance Check"} + Buff -- "Thua cuộc" --> Buff_Apply["💎 Kích hoạt Comeback Buff"] Buff_Apply --> A end + class Win_S,Win_T winStyle; + class Result_Logic,Post_Match,Buff,Buff_Apply initStyle; - %% Connections - 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 + %% Interactions (Dashed Lines) + S_Trap -.->|Cảnh báo| T_Check + S4 -.->|Sóng âm| T2 + T4 -.->|Collision ẩn| S_Check NS3 --> Loop ``` @@ -118,29 +132,116 @@ graph TD ## 🏗️ 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à. +### 1. Advanced Player & Camera State Machine + +Hệ thống điều khiển nhân vật không chỉ quản lý hành động mà còn điều phối **Camera Dynamics** để tăng cường cảm giác nhập vai và đồng bộ hóa hướng nhìn qua mạng. ```mermaid stateDiagram-v2 - [*] --> Idle - Idle --> Moving: Movement Input - Moving --> Running: Sprint Input - Running --> Idle: Stop - Moving --> Sneaking: Sneak Input + direction TB + + %% Định nghĩa các Style giả lập qua ghi chú (vì stateDiagram-v2 hạn chế classDef trực tiếp) - state "Airborne Logic" as Airborne { - Jump --> Falling - Falling --> Grounded + state "🕹️ GROUND LOCOMOTION (STEALTH & SPEED)" as Ground { + [*] --> Idle + + state Idle { + direction LR + I_Phys: Vel < 0.1m/s + I_Cam: Breathing Cycle (0.5Hz) + } + + Idle --> Moving: Input.mag > 0.1 + state Moving { + direction LR + M_Phys: Speed 2-4m/s + M_Cam: Head Bob (1.2Hz, Amp 0.05) + } + + Moving --> Sneaking: OnSneak (Hold) + state Sneaking { + direction LR + Sn_Phys: Speed 1.5m/s | Noise -50% + Sn_Cam: Height -0.5m | FOV 55 (Focus) + } + + Moving --> Sprinting: OnSprint (Hold) && Stamina > 0 + state Sprinting { + direction LR + Sp_Phys: Speed > 6.5m/s | Noise +100% + Sp_Cam: FOV 60->85 (Dynamic) | Motion Blur + } + + Sprinting --> Moving: Stamina == 0 || !SprintInput + Sneaking --> Moving: !SneakInput } + + state "🌪️ AIRBORNE & KINETIC IMPACT" as Air { + state Jump { + J_Phys: AddForce(Vector3.up * Power) + J_Cam: Instant Y-Kick (Recoil) + } + + state Falling { + F_Phys: Gravity * 1.5 (Fast Fall) + F_Cam: FOV Stretch | Wind SFX + } + + state Landing { + L_Phys: Impact Velocity Check + L_Cam: Hard/Soft Shake (Z-Axis Roll) + } + + Jump --> Falling: Vel.y < 0 + Falling --> Landing: IsGrounded == true + } + + state "⚡ ACTION & ABILITY LAYER" as Utility { + state Dashing { + D_Phys: Linear Velocity Burst (15m/s) + D_Cam: Lens Distortion (Radial) | Trail VFX + } + + state Interacting { + Int_Phys: Root Motion Lock + Int_Cam: Contextual Smooth Look-at + } + } + + state "🌐 NETWORK RECONCILIATION LAYER" as Net { + state InputAuthority { + IA: Local Prediction (Zero Latency) + IA: Buffer Tick N + } + state StateAuthority { + SA: Server Snapshot (Tick N-3) + SA: Verification & Correction + } + + IA --> SA: [Networked] CamRotation + SA --> IA: Teleport/Snap if Error > 0.5m + } + + %% Hệ thống góc nhìn bất đối xứng (Asymmetric Views) + state "🎭 ROLE SPECIFIC VIEWPORTS" as Roles { + state Seeker_FPS { + S_View: 1st Person POV + S_Logic: Raycast Flashlight | Noise Meter UI + } + state Trapper_STRAT { + T_View: Top-Down Orthographic / Isometric + T_Logic: Heatmap Overlay | CCTV Switcher + } + } + + %% Transitions chính + Ground --> Air: !IsGrounded (Coyote Time: 0.2s) + Air --> Ground: OnLand Event + Ground --> Utility: OnAbilityTrigger + Utility --> Ground: OnAnimationEnd - Moving --> Jump: Jump Input - Airborne --> Idle: Land - - Moving --> Dashing: Dash Input - Dashing --> Moving: Complete - - Interact --> Idle: Action Key + note left of Ground: Sync: [Networked] Velocity, MoveState + note right of Net: Fusion: FixedUpdateNetwork() Loop ``` ### 2. Environment Scanner & Interaction @@ -163,39 +264,58 @@ Trái tim của **HALLUCINATE** là hệ thống tạo mê cung đa thuật toá ```mermaid 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] + %% Định nghĩa Style + classDef lossStyle fill:#ffebee,stroke:#c62828,stroke-width:2px,color:#c62828; + classDef tier1Style fill:#fff8e1,stroke:#fbc02d,stroke-width:2px,color:#f57f17; + classDef tier2Style fill:#fff3e0,stroke:#fb8c00,stroke-width:2px,color:#e65100; + classDef tier3Style fill:#fbe9e7,stroke:#ff5722,stroke-width:2px,color:#bf360c; + classDef systemStyle fill:#f5f5f5,stroke:#424242,stroke-width:2px,color:#424242; + classDef winStyle fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20; + + %% Quy trình chính + Start(("💔 PLAYER LOSES ROUND")) --> Streak{{"📊 Check Loss Streak"}} + + %% Phân tầng Buff + subgraph Buff_Pools ["🔥 HỆ THỐNG CÂN BẰNG ĐỘNG (COMEBACK POOLS)"] + Streak -- "1 Trận" --> T1 + Streak -- "2 Trận" --> T2 + Streak -- "3+ Trận" --> T3 + + T1["🥉 Tier 1: Awakening
(Small Boosts)"] + T2["🥈 Tier 2: Evolution
(Tactical Advantage)"] + T3["🥇 Tier 3: Manifestation
(Game Changer)"] + + %% Ví dụ chỉ số (Tooltip-like) + T1 --- T1_Ex["+10% Speed
+15% Stamina Regen"] + T2 --- T2_Ex["Bẫy tàng hình (Trapper)
Giảm 50% tiếng ồn (Seeker)"] + T3 --- T3_Ex["Nhìn xuyên tường 5s
Hồi sinh 1 lần tại chỗ"] 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 + %% Giai đoạn áp dụng + T1 & T2 & T3 --> Selection{{"🎲 Selection Mode"}} + + Selection -- "Manual" --> P1["Người chơi tự chọn 1 trong 3 Buff"] + Selection -- "Auto" --> P2["Hệ thống chọn ngẫu nhiên"] + + P1 & P2 --> Apply["✨ Apply to Next Round Only
(Trạng thái: Active)"] - 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 + %% Kết quả vòng đấu sau + Apply --> Result{{"🏁 New Round Result?"}} - 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 + Result -- "🏆 WIN" --> Reset["♻️ Reset Streak
Remove All Buffs"] + Result -- "❌ LOSS" --> Increment["📈 Increase Streak
Progress to Next Tier"] + + %% Vòng lặp + Reset --> NewGame(("🎮 Fair Match")) + Increment --> Start + + %% Gán Style + class Start,Increment lossStyle; + class T1,T1_Ex tier1Style; + class T2,T2_Ex tier2Style; + class T3,T3_Ex tier3Style; + class Selection,P1,P2,Apply systemStyle; + class Result,Reset,NewGame winStyle; ``` --- @@ -207,85 +327,73 @@ Sử dụng **Photon Fusion (State Sync)** với cơ chế Client-Side Predictio ### 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 (Other Clients) + autonumber + + %% Định nghĩa các bên tham gia với Icon + participant IR as 🖱️ Input Reader (Local) + box rgb(235, 245, 255) "CLIENT (Input Authority)" + participant CP as 👤 Local Player
(Predictive Simulation) + end + box rgb(255, 243, 224) "NETWORK LAYER" + participant NT as 🌐 Photon Fusion Buffer + end + box rgb(232, 245, 233) "SERVER (State Authority)" + participant S as 🖥️ Headless Server
(Validation) + end + box rgb(243, 229, 245) "OTHER CLIENTS (Proxies)" + participant RP as 👥 Remote Proxies
(Interpolation) + end - 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} + %% --- GIAI ĐOẠN 1: THU THẬP INPUT --- + rect rgb(200, 230, 250) + Note over IR, CP: [TICK N] Giai đoạn lấy dữ liệu đầu vào + IR->>CP: OnMove(Vector2), OnJump(bool) + CP->>CP: Encode NetworkInputData {Buttons, Angles} + end + + %% --- GIAI ĐOẠN 2: DỰ ĐOÁN & GỬI DỮ LIỆU --- + rect rgb(255, 248, 225) + Note over CP, NT: [FixedUpdateNetwork] Khởi chạy vòng lặp mạng + CP->>CP: 🏃 Client-Side Prediction:
Áp dụng vận tốc & Physics ngay lập tức + CP->>NT: Reliable/Unreliable Input Packet + NT-->>S: Transport Layer (UDP/Photon Bolt) + end + + %% --- GIAI ĐOẠN 3: XÁC THỰC TẠI SERVER --- + rect rgb(232, 245, 233) + Note right of S: SERVER SIMULATION (Tick N) + S->>S: Dequeue Input từ Buffer + S->>S: Thực thi Logic: Move -> Collision Check -> Stamina + S->>S: Ghi đè [Networked] Properties (State Authority) + end + + %% --- GIAI ĐOẠN 4: ĐỒNG BỘ HÓA & HIỆU CHỈNH --- + S-->>NT: Broadcast State Snapshot (Tick N) - 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) + par Hồi đáp Local Player + NT-->>CP: State Snapshot + Note over CP: 🔄 RECONCILIATION + alt Nếu vị trí sai lệch > Threshold + CP->>CP: Hard Snap / Resimulate từ Tick lỗi + else Khớp dữ liệu + CP->>CP: Tiếp tục Simulation + end + and Cập nhật các Player khác + NT-->>RP: State Snapshot + Note over RP: 🎞️ INTERPOLATION + RP->>RP: Lerp từ Snapshot (N-1) sang Snapshot (N) + end + + %% --- GIAI ĐOẠN 5: HIỂN THỊ (MONOBEHAVIOUR) --- + rect rgb(245, 245, 245) + Note over CP, RP: [LateUpdate / Render Loop] + CP->>CP: Update Visual: Camera Shake, VFX + RP->>RP: Render Smooth Mesh Motion + end ``` --- -## 📂 Cấu trúc Thư mục Dự án (Project 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/ # 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. @@ -322,28 +430,8 @@ Khi Trapper để xổng mất con mồi, mê cung sẽ hiến tế sự ổ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). @@ -355,16 +443,122 @@ graph TD --- -## 🤝 Hướng dẫn Cài đặt (Installation) +## 📂 Cấu trúc Thư mục Dự án (Project 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 +📦 HALLUCINATE +├── 🌸 Assets/ (Trái tim của trò chơi) +│ ├── 📜 Scripts/ (Phép thuật điều khiển logic) +│ │ ├── 🏷️ Attributes/ # Tùy biến Inspector xinh xắn +│ │ ├── 🎥 Camera Controller/ # Ánh nhìn của nhân vật +│ │ ├── 🛠️ Debug/ # Đội cứu hộ lỗi (Fix-it!) +│ │ ├── 🌐 Fusion/ # Sợi dây kết nối mọi người (Networking) +│ │ │ └── 🚀 BasicSpawner.cs +│ │ ├── 🏗️ GameSetup/ # Kiến tạo thế giới ảo +│ │ │ ├── 🌀 Maze/ # Mê cung huyền bí +│ │ │ │ ├── 🐾 Crawler.cs # Những bước chân ngẫu nhiên +│ │ │ │ ├── 🌳 Prims.cs # Cây khung tối tiểu +│ │ │ │ ├── 🧵 Wilsons.cs # Bước đi không vòng lặp +│ │ │ │ └── 🗺️ Maze.cs # Nhạc trưởng mê cung +│ │ │ └── 🧍 CharacterAutoSetup.cs +│ │ ├── 🖱️ Interactables/ # Những vật thể biết nói +│ │ │ ├── 🚪 DoorInteractable.cs +│ │ │ ├── 💡 LampInteractable.cs +│ │ │ └── 💎 BaseInteractable.cs +│ │ ├── 📐 Interface/ # Bản thiết kế chung (IInteractable) +│ │ ├── 🏃‍♀️ Player Controller/ # Linh hồn của Gameplay +│ │ │ ├── 🧠 PlayerStateMachine.cs +│ │ │ ├── ⌨️ InputReader.cs +│ │ │ └── 🎭 States/ # Cảm xúc hành động (Idle, Run, Jump...) +│ │ ├── ⚡ Optimization/ # Phép màu mượt mà (60 FPS!) +│ │ ├── 🖥️ UI/ # Giao diện dễ thương +│ │ └── 🎆 VFX/ # Bụi tiên và ánh sáng +│ ├── 🧸 Prefabs/ # Những món đồ chơi dựng sẵn +│ ├── 📖 document/ # Sách bí kíp (Design & Diagrams) +│ ├── 🎬 Scenes/ # Những sân khấu kịch +│ ├── 🎨 Materials/ # Lớp áo lấp lánh (Cell-Shading) +│ ├── 👸 Models/ # Những cư dân Anime 3D +│ ├── 💃 Animation/ # Điệu nhảy của nhân vật +│ ├── 🔌 Photon/ # Cổng dịch chuyển không gian (SDK) +│ ├── 🅰️ TextMesh Pro/ # Những dòng chữ nghệ thuật +│ └── ⚙️ Settings/ # Cấu hình thế giới (URP & Physics) +├── 🛠️ ProjectSettings/ # Quy tắc của vũ trụ Unity +│ ├── 🏷️ TagManager.asset # Phân loại tầng mây +│ ├── 🌍 DynamicsManager.asset # Trọng lực & Va chạm +│ └── 📡 MultiplayerManager.asset # Quy tắc chơi chung +├── 📦 Packages/ # Những chiếc túi thần kỳ +└── 📝 README.md # Lời chào từ Creator (｡•̀ᴗ-)✧ +``` + +--- + +## 🤝 Hướng dẫn Cài đặt & Khởi chạy (Installation & Setup) + +Để trải nghiệm **HALLUCINATE** một cách mượt mà nhất, vui lòng thực hiện theo các bước chi tiết dưới đây: + +### 1. Yêu cầu Hệ thống +* **Unity Editor:** Phiên bản **6000.3.10f1 (Unity 6)** trở lên. +* **Hệ điều hành:** Windows 10/11 hoặc macOS (M1/M2/Intel). +* **Disk Space:** Tối thiểu 5GB trống để chứa Project và Library. + +### 2. Tải về & Mở dự án 1. **Clone Repository:** ```bash git clone https://github.com/OnlyScove/HALLUCINATE.git ``` -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`. +2. Mở **Unity Hub**, chọn **Add** -> **Add project from disk**. +3. Tìm đến thư mục vừa clone và nhấn **Open**. Chờ Unity Hub tải các Packages cần thiết (có thể mất vài phút). + +### 3. Cấu hình Photon Fusion (Bắt buộc) +Trò chơi yêu cầu **AppID** hợp lệ để hoạt động qua mạng: +1. Đăng nhập vào [Photon Engine Dashboard](https://dashboard.photonengine.com/). +2. Tạo một ứng dụng mới với loại App là **Fusion**. +3. Sao chép **App ID** vừa tạo. +4. Trong Unity Editor, đi đến: `Photon` -> `Fusion` -> `Network Project Settings`. +5. Dán App ID vào mục **App Id Fusion** (cho cả Realtime và Fusion). +6. Đảm bảo **Network Mode** được đặt là `Client/Server` (để hỗ trợ State Authority). + +### 4. Khởi chạy Trò chơi +1. Mở Scene chính tại: `Assets/Scenes/Main Scene.unity`. +2. Sử dụng **Smart Bootstrapper** (nằm ở thanh Menu trên cùng) để tự động cấu hình Runner. +3. Nhấn nút **Play** trong Unity Editor. +4. Để test Multiplayer, bạn có thể build ra file `.exe` hoặc sử dụng công cụ **ParrelSync** (nếu đã cài) để chạy hai instance cùng lúc. --- -**© 2026 ONLYSCOVE STUDIOS.** +## 💖 Support & Community + +

+ + Stars + + + Forks + + + Follow + +

+ +

+ + Buy Me A Coffee + + + Discord + + + Ko-fi + +

+ +

+ Visitors +

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