tracy-for-unity/unity_examples

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 - 5分钟快速集成指南
2. TracyExamples.cs - 查看代码示例
3. ../UNITY_INTEGRATION_GUIDE.md - 完整的集成文档

有经验的用户

快速集成步骤：

# 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
• 绘制实时数值
• 发送消息和日志
• 线程命名

导出函数:

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)

配置选项:

-DTRACY_ENABLE=ON         # 启用 Tracy
-DTRACY_ON_DEMAND=ON      # 按需分析模式
-DTRACY_ROOT=path         # Tracy 根目录

C# 脚本相关

TracyWrapper.cs

Tracy 的 C# API 封装，提供简洁易用的接口。

核心 API:

// 初始化
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. 游戏开发性能优化

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. 资源加载分析

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 系统性能追踪

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. 网络同步分析

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. 渲染管线优化

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)

编译:

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+

编译:

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

编译:

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+

编译:

# 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

编译:

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

快速检查清单:

• DLL 文件在正确的 Plugins 目录
• Plugin Import Settings 配置正确
• Tracy Profiler 正在运行
• 防火墙允许端口 8086
• Tracy.Initialize() 已被调用
• Unity Console 显示初始化消息
• 代码中使用了 Tracy.Zone() 或 ZoneScoped
• TracyManager 组件已添加到场景

获取帮助

如果遇到问题：

1. 查看 QUICKSTART.md 的故障排除章节
2. 查看 完整集成指南
3. 查看 Tracy 官方文档
4. 检查 Unity Console 的错误消息

📚 相关资源

文档

• 快速开始指南 - 5分钟集成
• 完整集成指南 - 详细文档
• Tracy 官方手册 - PDF

链接

• Tracy GitHub - 官方仓库
• Tracy 演示视频 - YouTube
• Unity Native Plugins - 官方文档

示例项目

本目录中的示例展示了：

• 基本的 Zone 使用
• 性能数据绘制
• 协程追踪
• 多线程支持
• 最佳实践

🤝 贡献

欢迎改进和建议！

如果你有更好的实现方式或发现了问题，请：

1. 修改代码
2. 测试你的更改
3. 分享你的改进

📄 许可证

• Tracy: BSD 3-Clause License
• 本示例代码: MIT License

🎉 开始使用

现在你已经了解了整体结构，可以开始集成了！

下一步: 打开 QUICKSTART.md 开始 5 分钟快速集成！

---

祝你使用愉快！ 🚀

如有任何问题，欢迎查阅文档或在社区寻求帮助。