485 lines
10 KiB
Markdown
485 lines
10 KiB
Markdown
# 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 分钟快速集成！
|
||
|
||
---
|
||
|
||
**祝你使用愉快！** 🚀
|
||
|
||
如有任何问题，欢迎查阅文档或在社区寻求帮助。
|
||
|