tracy-for-unity/unity_examples/QUICKSTART.md

Tracy Unity 集成快速开始指南

本指南将帮助你快速将 Tracy 性能分析器集成到 Unity 项目中。

---

🚀 快速开始（5 分钟集成）

步骤 1: 准备 Tracy

1. 克隆或下载 Tracy 仓库：

git clone https://github.com/wolfpld/tracy.git

2. （可选）编译 Tracy Profiler 工具：

cd tracy/profiler
# Windows: 使用 Visual Studio 打开并编译
# macOS/Linux: 
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

步骤 2: 编译 Unity Plugin

Windows (使用 CMake + Visual Studio)

# 在 unity_examples 目录下
mkdir build
cd build

# 配置（修改 TRACY_ROOT 路径指向你的 tracy 目录）
cmake .. -G "Visual Studio 17 2022" -A x64 ^
    -DTRACY_ROOT="D:/path/to/tracy" ^
    -DTRACY_ENABLE=ON ^
    -DTRACY_ON_DEMAND=ON

# 编译
cmake --build . --config Release

编译完成后，DLL 文件在 build/Unity/Plugins/x86_64/UnityTracyPlugin.dll

macOS

# 在 unity_examples 目录下
mkdir build && cd build

# 配置
cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DTRACY_ROOT="/path/to/tracy" \
    -DTRACY_ENABLE=ON \
    -DTRACY_ON_DEMAND=ON

# 编译
make -j8

编译完成后，动态库在 build/Unity/Plugins/macOS/UnityTracyPlugin.dylib

Linux

# 在 unity_examples 目录下
mkdir build && cd build

# 配置
cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DTRACY_ROOT="/path/to/tracy" \
    -DTRACY_ENABLE=ON \
    -DTRACY_ON_DEMAND=ON

# 编译
make -j8

编译完成后，动态库在 build/Unity/Plugins/Linux/x86_64/UnityTracyPlugin.so

步骤 3: 集成到 Unity 项目

1. 复制 Plugin 文件

将编译好的 Plugin 复制到 Unity 项目：

YourUnityProject/
└── Assets/
    └── Plugins/
        ├── x86_64/
        │   └── UnityTracyPlugin.dll          # Windows
        ├── macOS/
        │   └── UnityTracyPlugin.dylib        # macOS
        └── Linux/
            └── x86_64/
                └── UnityTracyPlugin.so       # Linux

2. 复制 C# 脚本

将以下文件复制到 Unity 项目：

YourUnityProject/
└── Assets/
    └── Scripts/
        └── Tracy/
            ├── TracyWrapper.cs      # Tracy C# API
            ├── TracyManager.cs      # Tracy 管理器
            └── TracyExamples.cs     # 使用示例（可选）

3. 配置 Plugin 导入设置

在 Unity Editor 中：

• 选择 UnityTracyPlugin.dll（或 .dylib/.so）
• 在 Inspector 中设置平台：
  • Windows: 勾选 x86_64
  • macOS: 勾选 macOS
  • Linux: 勾选 Linux x86_64

步骤 4: 在场景中使用

1. 添加 TracyManager

在你的主场景中：

• 创建空 GameObject，命名为 "TracyManager"
• 添加 TracyManager 组件
• 在 Inspector 中配置选项

2. 在代码中使用 Tracy

using UnityEngine;
using TracyProfiler;

public class MyGameScript : MonoBehaviour
{
    void Update()
    {
        // 方式 1: 使用 using 语句（推荐）
        using (Tracy.Zone("MyGameScript.Update"))
        {
            DoSomething();
        }
        
        // 方式 2: 手动开始/结束
        Tracy.BeginZone("CustomZone");
        DoSomethingElse();
        Tracy.EndZone();
        
        // 绘制数值
        Tracy.Plot("Enemy Count", enemyCount);
        
        // 发送消息
        if (playerDied)
        {
            Tracy.Message("Player died");
        }
    }
    
    void DoSomething()
    {
        using (Tracy.Zone("DoSomething"))
        {
            // 你的代码
        }
    }
}

步骤 5: 启动 Tracy Profiler 并连接

1. 启动 Tracy Profiler

# Windows
Tracy.exe

# macOS/Linux
./Tracy

2. 运行 Unity 游戏

在 Unity Editor 中按 Play，或运行构建的可执行文件。

3. 连接到 Tracy

Tracy Profiler 会自动发现本地网络中的 Tracy 客户端，点击连接即可开始分析。

---

📊 使用 Tracy 分析性能

查看性能数据

Tracy Profiler 界面主要区域：

1. 时间线视图

   • 显示所有 Zone 的执行时间
   • 颜色表示不同的调用栈深度
   • 可以缩放和平移

2. 统计视图

   • 函数调用次数
   • 总耗时、平均耗时、最小/最大耗时
   • 排序和筛选功能

3. 帧视图

   • 查看每帧的性能
   • 识别帧率波动
   • 帧时间分布

4. Plot 视图

   • 查看 Tracy.Plot() 绘制的数值曲线
   • 实时监控变量变化

常用快捷键

• 鼠标滚轮: 缩放时间线
• 鼠标中键拖拽: 平移时间线
• 鼠标左键: 选择 Zone 查看详情
• Ctrl + F: 搜索函数
• Ctrl + Z: 放大到选中的 Zone

---

🔧 常见问题排查

问题 1: DLL 加载失败

错误信息: DllNotFoundException: UnityTracyPlugin

解决方案:

1. 确认 DLL 文件在正确的目录
2. 检查 Plugin Import Settings 的平台配置
3. 确认 DLL 架构与 Unity 项目匹配（x64/x86）
4. Windows: 检查是否缺少 vcruntime140.dll（安装 Visual C++ Redistributable）

问题 2: Tracy Profiler 无法连接

症状: Tracy Profiler 中看不到 Unity 应用

解决方案:

1. 确认防火墙允许 TCP 端口 8086
2. 检查 TRACY_ON_DEMAND 宏是否正确定义
3. 确认 Tracy.Initialize() 已被调用
4. 检查 Unity Console 是否有 Tracy 初始化消息

// 在 Unity Console 应该看到:
// [Tracy] 性能分析器已初始化

问题 3: 性能数据不显示

症状: Tracy 已连接，但看不到任何 Zone

解决方案:

1. 确认代码中使用了 Tracy.Zone() 或 ZoneScoped
2. 确认 Tracy.MarkFrame() 在每帧被调用
3. 检查是否定义了 TRACY_ENABLE 编译符号
4. 在 Unity Editor 中，确认 Tracy Manager 的 "Enable On Start" 已勾选

问题 4: 编译错误

常见编译错误:

1. 找不到 Tracy.hpp

   fatal error: tracy/Tracy.hpp: No such file or directory
   

   解决: 检查 TRACY_ROOT 路径是否正确

2. 链接错误 (Windows)

   error LNK2019: unresolved external symbol
   

   解决: 确认链接了 ws2_32.lib 和 dbghelp.lib

3. 链接错误 (Linux)

   undefined reference to `pthread_create'
   

   解决: 添加 -lpthread -ldl 链接选项

问题 5: Android/iOS 构建问题

Android:

1. 使用 Android NDK 编译
2. 确保为所有需要的 ABI 编译（armeabi-v7a, arm64-v8a）
3. 将 .so 文件放在 Assets/Plugins/Android/libs/{ABI}/

iOS:

1. 编译为静态库（.a）
2. 在 Unity Build Settings 中设置 "Target SDK" 为 "Device SDK"
3. 确保代码签名正确

---

🎯 最佳实践

1. Zone 命名规范

// ✅ 好的命名 - 清晰、描述性
using (Tracy.Zone("PlayerController.Move"))
using (Tracy.Zone("AI.UpdatePathfinding"))
using (Tracy.Zone("Render.DrawTerrain"))

// ❌ 不好的命名 - 模糊、无意义
using (Tracy.Zone("Function1"))
using (Tracy.Zone("Update"))
using (Tracy.Zone("Test"))

2. 适度使用 Zone

void Update()
{
    // ✅ 追踪主要的逻辑块
    using (Tracy.Zone("Update"))
    {
        using (Tracy.Zone("ProcessInput"))
        {
            ProcessInput();  // 追踪大块逻辑
        }
        
        UpdateGameLogic();   // 内部有自己的 Zone
    }
}

// ❌ 过度追踪会增加开销
void BadExample()
{
    for (int i = 0; i < 10000; i++)
    {
        using (Tracy.Zone($"Iteration {i}"))  // 太多 Zone！
        {
            DoSomething();
        }
    }
}

3. 使用条件编译

// 在生产构建中禁用细粒度追踪
#if TRACY_ENABLE
    using (Tracy.Zone("DetailedAnalysis"))
    {
        // 详细的性能分析代码
    }
#endif

4. 监控关键指标

void LateUpdate()
{
    // 监控帧率
    Tracy.Plot("FPS", 1.0f / Time.deltaTime);
    
    // 监控内存
    Tracy.Plot("Memory (MB)", GC.GetTotalMemory(false) / 1024.0 / 1024.0);
    
    // 监控对象计数
    Tracy.Plot("Enemy Count", enemies.Count);
    Tracy.Plot("Active Particles", particleSystem.particleCount);
    
    // 监控物理
    Tracy.Plot("Rigidbodies", FindObjectsOfType<Rigidbody>().Length);
}

5. 多线程命名

using System.Threading;

void WorkerThread()
{
    Tracy.SetThreadName("Worker Thread");
    
    while (running)
    {
        using (Tracy.Zone("WorkerThread.Process"))
        {
            ProcessData();
        }
    }
}

---

📚 进阶主题

自定义构建配置

在 Unity 项目中创建 link.xml 防止代码剥离：

<linker>
    <assembly fullname="Assembly-CSharp">
        <namespace fullname="TracyProfiler" preserve="all"/>
    </assembly>
</linker>

持久化性能数据

Tracy 支持保存性能数据到文件：

1. 在 Tracy Profiler 中，点击 "Save trace"
2. 选择保存位置（.tracy 文件）
3. 之后可以用 Tracy Profiler 打开查看

集成到 CI/CD

可以在自动化测试中使用 Tracy：

public class PerformanceTest
{
    [Test]
    public void TestPerformance()
    {
        Tracy.Initialize();
        
        using (Tracy.Zone("PerformanceTest"))
        {
            // 运行性能测试
            RunGameLoop(100); // 运行 100 帧
        }
        
        Tracy.Shutdown();
        
        // 分析结果...
    }
}

---

🔗 资源链接

• Tracy 官方仓库
• Tracy 官方手册
• Unity Native Plugin 文档
• 本项目的完整文档: UNITY_INTEGRATION_GUIDE.md

---

💡 技巧和提示

1. 使用 Release 构建进行性能测试

   • Debug 构建会有大量额外开销
   • 在 Unity 中创建专门的 "Profiling" 构建配置

2. 关闭 V-Sync 测试真实性能

   • V-Sync 会限制帧率
   • 在 Project Settings > Quality 中关闭

3. 使用 Tracy 的统计功能

   • 查看函数调用次数
   • 识别被频繁调用的函数

4. 比较不同实现

   • 使用 Tracy 比较算法性能
   • A/B 测试优化效果

5. 定期保存 Trace 文件

   • 记录性能基准
   • 跟踪性能变化趋势

---

🎉 完成！

现在你已经成功将 Tracy 集成到 Unity 项目中了！

开始使用 Tracy 分析你的游戏性能，找出瓶颈，优化代码吧！

如有问题，请参考完整文档 UNITY_INTEGRATION_GUIDE.md 或访问 Tracy 官方仓库。