ninemine/tracy-for-unity

Fork 0

Files

ninemine 43de86ee31 Init

2025-11-26 14:35:58 +08:00

10 KiB

Raw Blame History

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            # 使用示例和最佳实践

🚀 快速开始

新手用户

如果你是第一次使用，请按以下顺序阅读：

QUICKSTART.md - 5分钟快速集成指南
TracyExamples.cs - 查看代码示例
../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)
- 帧时间
- 内存使用
- 渲染统计
- 物理对象数量

使用方法:

在场景中创建空 GameObject
添加 TracyManager 组件
配置 Inspector 中的选项
运行游戏

Inspector 选项:

Enable On Start: 启动时自动初始化
Mark Frames: 每帧自动标记
Monitor Frame Rate: 监控帧率
Monitor Memory: 监控内存
Monitor Rendering: 监控渲染
Monitor Physics: 监控物理

`TracyExamples.cs`

完整的使用示例和最佳实践。

包含示例:

✅ 基础 Zone 使用
✅ 计算密集型操作追踪
✅ 重度计算测试
✅ 对象池管理
✅ 协程性能追踪
✅ 自定义数据绘制
✅ 条件性能追踪

交互功能:

按 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 组件已添加到场景

获取帮助

如果遇到问题：

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

📚 相关资源

文档

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

链接

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

示例项目

本目录中的示例展示了：

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

🤝 贡献

欢迎改进和建议！

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

修改代码
测试你的更改
分享你的改进

📄 许可证

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

🎉 开始使用

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

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

祝你使用愉快！ 🚀

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

10 KiB Raw Blame History Unescape Escape