# Fire Unity Project / Fire Unity 项目
This repository is a sample project based on **Unity 2021.3 LTS**. It contains multiple art asset packages (Low Poly environments, characters, props, etc.) and a self-developed VR conversion tool package `Packages/com.fire.vrconverter`. Through this project, you can quickly experience or build a basic runtime environment for Fire VR.
本仓库是一个基于 **Unity 2021.3 LTS** 的示例项目，包含多个美术资源包（低多边形环境、角色、道具等）和一个自研的 VR 转换工具包 `Packages/com.fire.vrconverter`。通过该项目，你可以快速体验或搭建 Fire VR 的基础运行环境。
---
## Project Introduction / 项目简介
**Fire** 是一个结合 **VR 技术与音乐治疗** 的创新项目，旨在为不同群体提供独特的虚拟体验。
### 🎯 核心目标
- **辅助游疗**：针对失语症人群，设计了专业的辅助治疗游戏。这些游戏内容由团队中两名音乐师范专业的同学精心编写，旨在通过音乐与互动的结合，辅助患者进行康复训练（项目目前仍处于积极开发中）。
- **治愈休闲**：面向大众群体，提供一个治愈、休闲且具备社交功能的虚拟空间。
### 🌟 主要玩法
项目构建了多个风格各异的**小场景**，用户通过“门框”来解锁并穿梭于这些场景之间：
- **沉浸观景**：在每个小场景中，用户可以通过 VR 设备身临其境地欣赏精美景色，放松身心。
- **趣味互动**：游玩场景内的小游戏，赢取**游戏代币**。
- **个性化收集**：使用代币兑换更多游戏道具，丰富互动体验。
### 🛠️ 技术架构 / Technology Stack
本项目基于 **Unity 2021.3 LTS** 开发，采用现代化的技术栈以确保性能与扩展性：
- **渲染管线**：采用 **Universal Render Pipeline (URP)**，在保证 VR 高帧率要求的同时提供优质的画面表现。
- **VR 框架**：基于 **XR Interaction Toolkit (XRI)** 和 **OpenXR** 标准，支持主流 VR 设备（Oculus/Meta Quest, HTC Vive 等）。
- **自研核心工具**：
- **Fire VR Converter**：一键将普通 3D 项目转换为 VR 项目，自动配置 XR 环境。
- **Focus Optimizer**：针对 VR 场景的性能优化工具。
- **Pose Drive**：处理 VR 下的手部姿态与交互动画。
- **Version Management Assistant**：辅助项目版本管理与迭代。
---
## Environment Requirements / 环境要求
- **OS**: Windows 10 or later.
- **Unity**: Unity 2021.3 LTS (with Universal RP and XR modules installed).
- **Git**: Git 2.30+, accessible via HTTPS or SSH.
- **系统**：Windows 10 或更高版本。
- **Unity**：Unity 2021.3 LTS（已安装 Universal RP、XR 模块）。
- **Git**：Git 2.30+，可通过 HTTPS 或 SSH 访问 GitHub。
---
## Repository Structure / 仓库结构
- `Assets/`: All scenes, models, materials, and script resources.
- `Packages/`: Unity Package dependencies and local packages (e.g., `com.fire.vrconverter`).
- `ProjectSettings/`: Global configuration for the Unity project.
- `UserSettings/`: Local settings (can be ignored by version control).
- `Logs/`, `Library/`, `obj/`: Generated by Unity/IDE, excluded via `.gitignore`.
- `Assets/`：全部场景、模型、材质、脚本资源。
- `Packages/`：Unity Package 依赖及本地包（例如 `com.fire.vrconverter`）。
- `ProjectSettings/`：Unity 项目的全局配置。
- `UserSettings/`：本地化设置（可忽略版本控制）。
- `Logs/`、`Library/`、`obj/` 等目录为 Unity/IDE 生成，可通过 `.gitignore` 排除。
---
## Quick Start / 快速开始
### 1. Clone the Repository / 克隆仓库
```powershell
git clone https://github.com/lyzbcy/fire.git
cd fire
```
If using SSH / 如使用 SSH：`git clone git@github.com:lyzbcy/fire.git`
### 2. Open Unity / 打开 Unity
- Launch Unity Hub and select **Open**, pointing to the repository root directory.
- First-time import may take a while; please wait for script compilation to finish.
- 启动 Unity Hub，选择 **Open** 指向仓库根目录。
- 首次导入可能耗时较长，请等待脚本编译完成。
### 3. Run Sample Scene / 运行示例场景
- In `Assets/`, select any sample scene (e.g., environment demo or VR scenes) and click **Play** to preview in the editor.
- 在 `Assets/` 中选择任意示例场景（例如环境演示场景，或 VR 相关场景），点击 **Play** 进入编辑器预览。
---
## VR Project Converter / VR 项目转换工具
The repository includes the `Fire VR Converter` located at `Packages/com.fire.vrconverter`. For detailed usage, please refer to the `README.md` inside that package.
**Core Features:**
- Automatically adds required XR Unity Packages (XR Management / OpenXR / XR Interaction Toolkit).
- Generates and configures `XR General Settings` and `XR Manager Settings`.
- Creates or updates the XR Origin / VR Rig (Camera, Controllers, Interaction Manager, etc.) in the current scene.
仓库内置 `Fire VR Converter`，位于 `Packages/com.fire.vrconverter`，其详细使用方式见包内 `README.md`。
**核心能力：**
- 自动写入 XR 所需的 Unity Package（XR Management / OpenXR / XR Interaction Toolkit）。
- 生成并配置 `XR General Settings`、`XR Manager Settings`。
- 在当前场景创建或更新 XR Origin / VR Rig（摄像机、左右手控制器、Interaction Manager 等）。
### Quick Guide / 快速指引
1. Open Unity menu: `Tools > Fire VR > Convert Current Project to VR...` (or `Tools > Fire VR > 一键转换当前项目为VR...`).
2. Click **Execute All Steps (Recommended)** in the popup window.
3. Wait for the logs to complete; a runnable VR Rig will be generated in the scene.
1. 打开 Unity 菜单 `Tools > Fire VR > 一键转换当前项目为VR...`
2. 在弹出窗口中点击 **一键执行所有步骤（推荐）**。
3. 等待日志提示完成后，场景会生成可运行的 VR Rig。
For advanced operations and troubleshooting, see `Packages/com.fire.vrconverter/README.md`.
更多高级操作（分步执行、常见问题）请参考 `Packages/com.fire.vrconverter/README.md`。
---
## Git Workflow / Git 协作流程
> Usage example with main repository `https://github.com/lyzbcy/fire`.
> 以下示例使用主仓库 `https://github.com/lyzbcy/fire`。
### 1. Sync Latest Code / 同步最新代码
```powershell
git pull origin main
```
Replace branch name if collaborating on multiple branches.
如有多分支协作，替换为对应分支名称。
### 2. Develop & Commit / 开发与提交
```powershell
git status # Check current changes / 查看当前改动
git add <file|.> # Stage changes / 暂存
git commit -m "feat: Description of changes"
```
### 3. Push to Remote / 推送到远程
```powershell
git push origin <branch>
```
### 4. Create/Update Feature Branch / 创建/更新功能分支
```powershell
git checkout -b feature/my-task # New branch / 新分支
git push -u origin feature/my-task
```
### 5. Resolve Conflicts / 处理冲突
- If `git pull --rebase origin <branch>` shows conflicts, resolve them in the editor, then `git add` and `git rebase --continue`.
- Keep commit history clean; use `git status` and `git diff` to check when necessary.
- `git pull --rebase origin <branch>` 同步时若提示冲突，在编辑器中解决后重新 `git add`、`git rebase --continue`。
- 保持提交记录整洁，必要时使用 `git status`、`git diff` 检查。
---
## FAQ / 常见问题
- **Long import time on first open?**
- This is normal. Please wait for Unity to complete asset and script compilation.
- **首次打开项目导入时间较长：** 属于正常现象，等待 Unity 完成 Asset 和脚本编译即可。
- **Git line ending warnings?**
- Windows/Unity generates CRLF. You can keep default settings or unify them in `.gitattributes`.
- **Git 提示行尾符差异：** Windows/Unity 会生成 CRLF，可保留默认设置或在 `.gitattributes` 中统一。
- **Permission denied when pushing?**
- Ensure you have collaborator access on GitHub or are using correct credentials (PAT/SSH Key).
- **权限不足无法推送：** 确认已在 GitHub 上添加协作者权限或使用正确的凭证（个人访问令牌/SSH Key）。
If you need more help, please open an Issue or contact the maintainers. Happy coding!
如需更多帮助，可在 Issue 中提问或联系项目维护者。祝开发顺利！