tracy-for-unity/unity_examples/README.md

# 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 分钟快速集成！

---

**祝你使用愉快！** 🚀

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