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 / 克隆仓库

git clone https://github.com/lyzbcy/fire.git
cd fire

If using SSH / 如使用 SSH：git clone [email protected]: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.

4. 打开 Unity 菜单 Tools > Fire VR > 一键转换当前项目为VR...

5. 在弹出窗口中点击 一键执行所有步骤（推荐）。

6. 等待日志提示完成后，场景会生成可运行的 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 / 同步最新代码

git pull origin main

Replace branch name if collaborating on multiple branches. 如有多分支协作，替换为对应分支名称。

2. Develop & Commit / 开发与提交

git status               # Check current changes / 查看当前改动
git add <file|.>         # Stage changes / 暂存
git commit -m "feat: Description of changes"

3. Push to Remote / 推送到远程

git push origin <branch>

4. Create/Update Feature Branch / 创建/更新功能分支

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 中提问或联系项目维护者。祝开发顺利！