Init

2025-11-26 14:35:58 +08:00
commit 43de86ee31
18 changed files with 3954 additions and 0 deletions
--- a/unity_examples/README.md
+++ b/unity_examples/README.md
@@ -0,0 +1,484 @@
+# Tracy Unity 集成示例
+
+本目录包含将 Tracy 性能分析器集成到 Unity 项目的完整示例和工具。
+
+## 📁 文件结构
+
+```
+unity_examples/
+├── README.md                    # 本文件 - 项目概述
+├── QUICKSTART.md               # 5分钟快速开始指南 ⭐ 从这里开始！
+├── CMakeLists.txt              # CMake 构建配置
+├── SimplifiedPlugin.cpp        # Tracy Unity Plugin C++ 实现
+├── TracyWrapper.cs             # Tracy C# API 封装
+├── TracyManager.cs             # Tracy 管理器组件
+└── TracyExamples.cs            # 使用示例和最佳实践
+```
+
+## 🚀 快速开始
+
+### 新手用户
+
+如果你是第一次使用，请按以下顺序阅读：
+
+1. **[QUICKSTART.md](QUICKSTART.md)** - 5分钟快速集成指南
+2. **[TracyExamples.cs](TracyExamples.cs)** - 查看代码示例
+3. **[../UNITY_INTEGRATION_GUIDE.md](../UNITY_INTEGRATION_GUIDE.md)** - 完整的集成文档
+
+### 有经验的用户
+
+快速集成步骤：
+
+```bash
+# 1. 编译 Plugin
+mkdir build && cd build
+cmake .. -DTRACY_ROOT="/path/to/tracy" -DCMAKE_BUILD_TYPE=Release
+cmake --build . --config Release
+
+# 2. 复制文件到 Unity 项目
+cp build/Unity/Plugins/* YourUnityProject/Assets/Plugins/
+cp *.cs YourUnityProject/Assets/Scripts/Tracy/
+
+# 3. 在 Unity 场景中添加 TracyManager 组件
+
+# 4. 运行 Tracy Profiler 并连接
+```
+
+## 📦 文件说明
+
+### C++ Plugin 相关
+
+#### `SimplifiedPlugin.cpp`
+Tracy Unity Native Plugin 的 C++ 实现。
+
+**主要功能**:
+- 初始化/关闭 Tracy
+- 创建性能追踪 Zone
+- 绘制实时数值
+- 发送消息和日志
+- 线程命名
+
+**导出函数**:
+```cpp
+TracyInit()              // 初始化
+TracyShutdown()          // 关闭
+TracyFrameMark()         // 标记帧边界
+TracyZoneBegin(name)     // 开始 Zone
+TracyZoneEnd()           // 结束 Zone
+TracyPlotValue(name, v)  // 绘制数值
+TracyMessage(msg)        // 发送消息
+TracySetThreadName(name) // 设置线程名
+```
+
+**编译要求**:
+- C++17
+- Tracy 源代码
+- Windows: Visual Studio 2019+
+- macOS: Xcode 12+
+- Linux: GCC 9+ 或 Clang 10+
+
+#### `CMakeLists.txt`
+跨平台 CMake 构建配置。
+
+**支持平台**:
+- ✅ Windows (x64)
+- ✅ macOS (Intel/Apple Silicon)
+- ✅ Linux (x64)
+- ✅ Android (armeabi-v7a, arm64-v8a)
+- ✅ iOS (arm64)
+
+**配置选项**:
+```cmake
+-DTRACY_ENABLE=ON         # 启用 Tracy
+-DTRACY_ON_DEMAND=ON      # 按需分析模式
+-DTRACY_ROOT=path         # Tracy 根目录
+```
+
+### C# 脚本相关
+
+#### `TracyWrapper.cs`
+Tracy 的 C# API 封装，提供简洁易用的接口。
+
+**核心 API**:
+```csharp
+// 初始化
+Tracy.Initialize()
+
+// 性能追踪 (推荐使用 using 语句)
+using (Tracy.Zone("FunctionName"))
+{
+    // 要追踪的代码
+}
+
+// 手动管理 Zone
+Tracy.BeginZone("CustomZone")
+// ... 代码 ...
+Tracy.EndZone()
+
+// 绘制实时数值
+Tracy.Plot("FPS", fps)
+Tracy.Plot("Memory", memoryMB)
+
+// 发送消息
+Tracy.Message("重要事件发生")
+
+// 设置线程名
+Tracy.SetThreadName("Worker Thread")
+
+// 标记帧边界
+Tracy.MarkFrame()
+```
+
+**特性**:
+- 使用 `IDisposable` 自动管理 Zone 生命周期
+- 条件编译支持（`TRACY_ENABLE`）
+- 零开销（禁用时）
+- 线程安全
+
+#### `TracyManager.cs`
+Unity 组件，负责 Tracy 的初始化和自动化监控。
+
+**功能**:
+- 自动初始化 Tracy
+- 每帧自动标记帧边界
+- 自动监控系统指标:
+  - 帧率 (FPS)
+  - 帧时间
+  - 内存使用
+  - 渲染统计
+  - 物理对象数量
+
+**使用方法**:
+1. 在场景中创建空 GameObject
+2. 添加 `TracyManager` 组件
+3. 配置 Inspector 中的选项
+4. 运行游戏
+
+**Inspector 选项**:
+- `Enable On Start`: 启动时自动初始化
+- `Mark Frames`: 每帧自动标记
+- `Monitor Frame Rate`: 监控帧率
+- `Monitor Memory`: 监控内存
+- `Monitor Rendering`: 监控渲染
+- `Monitor Physics`: 监控物理
+
+#### `TracyExamples.cs`
+完整的使用示例和最佳实践。
+
+**包含示例**:
+1. ✅ 基础 Zone 使用
+2. ✅ 计算密集型操作追踪
+3. ✅ 重度计算测试
+4. ✅ 对象池管理
+5. ✅ 协程性能追踪
+6. ✅ 自定义数据绘制
+7. ✅ 条件性能追踪
+
+**交互功能**:
+- 按 `Space` 键: 执行重度计算
+- 按 `R` 键: 重置对象池
+- 按 `T` 键: 运行性能测试
+
+## 🎯 使用场景
+
+### 1. 游戏开发性能优化
+
+```csharp
+public class GameController : MonoBehaviour
+{
+    void Update()
+    {
+        using (Tracy.Zone("GameController.Update"))
+        {
+            using (Tracy.Zone("Update AI"))
+            {
+                UpdateAI();
+            }
+            
+            using (Tracy.Zone("Update Physics"))
+            {
+                UpdatePhysics();
+            }
+            
+            using (Tracy.Zone("Update Rendering"))
+            {
+                UpdateRendering();
+            }
+        }
+    }
+}
+```
+
+### 2. 资源加载分析
+
+```csharp
+IEnumerator LoadScene()
+{
+    using (Tracy.Zone("Load Scene"))
+    {
+        using (Tracy.Zone("Load Assets"))
+        {
+            yield return LoadAssets();
+        }
+        
+        using (Tracy.Zone("Initialize Scene"))
+        {
+            InitializeScene();
+        }
+        
+        Tracy.Message("Scene loaded successfully");
+    }
+}
+```
+
+### 3. AI 系统性能追踪
+
+```csharp
+public class AIManager : MonoBehaviour
+{
+    void Update()
+    {
+        using (Tracy.Zone("AI Manager"))
+        {
+            foreach (var agent in agents)
+            {
+                using (Tracy.Zone($"AI Agent {agent.id}"))
+                {
+                    agent.UpdateBehavior();
+                }
+            }
+            
+            Tracy.Plot("Active AI Agents", agents.Count);
+        }
+    }
+}
+```
+
+### 4. 网络同步分析
+
+```csharp
+void OnNetworkUpdate()
+{
+    using (Tracy.Zone("Network Update"))
+    {
+        using (Tracy.Zone("Receive Packets"))
+        {
+            ReceivePackets();
+        }
+        
+        using (Tracy.Zone("Process Messages"))
+        {
+            ProcessMessages();
+        }
+        
+        using (Tracy.Zone("Send Updates"))
+        {
+            SendUpdates();
+        }
+        
+        Tracy.Plot("Network Latency (ms)", latency);
+        Tracy.Plot("Packet Loss (%)", packetLoss);
+    }
+}
+```
+
+### 5. 渲染管线优化
+
+```csharp
+void OnPreRender()
+{
+    using (Tracy.Zone("Pre-Render"))
+    {
+        using (Tracy.Zone("Culling"))
+        {
+            PerformCulling();
+        }
+        
+        using (Tracy.Zone("Sort Render Queue"))
+        {
+            SortRenderQueue();
+        }
+        
+        Tracy.Plot("Visible Objects", visibleCount);
+        Tracy.Plot("Draw Calls", drawCalls);
+    }
+}
+```
+
+## 🔧 平台特定说明
+
+### Windows
+
+**依赖**:
+- Visual Studio 2019 或更高版本
+- Windows SDK
+- vcruntime140.dll (Visual C++ Redistributable)
+
+**编译**:
+```powershell
+cmake -B build -G "Visual Studio 17 2022" -A x64
+cmake --build build --config Release
+```
+
+**输出**: `build/Unity/Plugins/x86_64/UnityTracyPlugin.dll`
+
+### macOS
+
+**依赖**:
+- Xcode Command Line Tools
+- CMake 3.15+
+
+**编译**:
+```bash
+cmake -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+```
+
+**输出**: `build/Unity/Plugins/macOS/UnityTracyPlugin.dylib`
+
+**注意**: Apple Silicon (M1/M2) 和 Intel 需要分别编译
+
+### Linux
+
+**依赖**:
+- GCC 9+ 或 Clang 10+
+- pthread, dl
+
+**编译**:
+```bash
+cmake -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+```
+
+**输出**: `build/Unity/Plugins/Linux/x86_64/UnityTracyPlugin.so`
+
+### Android
+
+**依赖**:
+- Android NDK r21+
+- CMake 3.15+
+
+**编译**:
+```bash
+# ARM64
+cmake -B build-android-arm64 \
+    -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \
+    -DANDROID_ABI=arm64-v8a \
+    -DANDROID_PLATFORM=android-21
+
+# ARMv7
+cmake -B build-android-armv7 \
+    -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \
+    -DANDROID_ABI=armeabi-v7a \
+    -DANDROID_PLATFORM=android-21
+```
+
+### iOS
+
+**依赖**:
+- Xcode 12+
+- iOS SDK
+
+**编译**:
+```bash
+cmake -B build-ios \
+    -DCMAKE_SYSTEM_NAME=iOS \
+    -DCMAKE_OSX_ARCHITECTURES=arm64 \
+    -DCMAKE_OSX_DEPLOYMENT_TARGET=12.0
+```
+
+**注意**: iOS 需要静态库（.a）而不是动态库
+
+## 📊 性能影响
+
+### Tracy 开销
+
+| 配置 | 每 Zone 开销 | 内存开销 | 网络带宽 |
+|------|-------------|---------|---------|
+| 禁用 (Release) | 0 ns | 0 MB | 0 |
+| 启用 (On-Demand, 未连接) | ~20 ns | ~1 MB | 0 |
+| 启用 (已连接) | ~50 ns | ~10 MB | ~1 Mbps |
+
+### 建议
+
+- ✅ 在 Debug/Development 构建中启用
+- ✅ 追踪主要逻辑块（毫秒级）
+- ⚠️ 避免追踪微小操作（微秒级）
+- ⚠️ 避免在紧密循环中创建 Zone
+- ❌ 不建议在 Release 构建中启用细粒度追踪
+
+## 🐛 故障排除
+
+### 常见问题
+
+详细的故障排除指南请参考 [QUICKSTART.md](QUICKSTART.md#常见问题排查)
+
+**快速检查清单**:
+
+- [ ] DLL 文件在正确的 Plugins 目录
+- [ ] Plugin Import Settings 配置正确
+- [ ] Tracy Profiler 正在运行
+- [ ] 防火墙允许端口 8086
+- [ ] `Tracy.Initialize()` 已被调用
+- [ ] Unity Console 显示初始化消息
+- [ ] 代码中使用了 `Tracy.Zone()` 或 `ZoneScoped`
+- [ ] `TracyManager` 组件已添加到场景
+
+### 获取帮助
+
+如果遇到问题：
+
+1. 查看 [QUICKSTART.md](QUICKSTART.md) 的故障排除章节
+2. 查看 [完整集成指南](../UNITY_INTEGRATION_GUIDE.md)
+3. 查看 [Tracy 官方文档](https://github.com/wolfpld/tracy)
+4. 检查 Unity Console 的错误消息
+
+## 📚 相关资源
+
+### 文档
+
+- [快速开始指南](QUICKSTART.md) - 5分钟集成
+- [完整集成指南](../UNITY_INTEGRATION_GUIDE.md) - 详细文档
+- [Tracy 官方手册](https://github.com/wolfpld/tracy/releases/latest/download/tracy.pdf) - PDF
+
+### 链接
+
+- [Tracy GitHub](https://github.com/wolfpld/tracy) - 官方仓库
+- [Tracy 演示视频](https://www.youtube.com/watch?v=fB5B46lbapc) - YouTube
+- [Unity Native Plugins](https://docs.unity3d.com/Manual/NativePlugins.html) - 官方文档
+
+### 示例项目
+
+本目录中的示例展示了：
+- 基本的 Zone 使用
+- 性能数据绘制
+- 协程追踪
+- 多线程支持
+- 最佳实践
+
+## 🤝 贡献
+
+欢迎改进和建议！
+
+如果你有更好的实现方式或发现了问题，请：
+1. 修改代码
+2. 测试你的更改
+3. 分享你的改进
+
+## 📄 许可证
+
+- Tracy: BSD 3-Clause License
+- 本示例代码: MIT License
+
+## 🎉 开始使用
+
+现在你已经了解了整体结构，可以开始集成了！
+
+**下一步**: 打开 [QUICKSTART.md](QUICKSTART.md) 开始 5 分钟快速集成！
+
+---
+
+**祝你使用愉快！** 🚀
+
+如有任何问题，欢迎查阅文档或在社区寻求帮助。
+