# profiler

> 性能分析工具。snapshot: 快照（FPS/内存/绘制调用/物理统计）。start/stop: 开始/停止分析会话。get_data: 收集帧级数据，含多维度采样、p99百分位、趋势退化检测、内存趋势、渲染统计。get_active_processes: 遍历场景树查找有 _process/_physics_process 的节点。get_signal_connections: 列出子树所有信号连接。运行时操作，仅影响当前执行上下文。如需持久化，请编辑 .tscn 文件。

| 属性 | 值 |
|------|-----|
| 所属层 | headless |
| 安全级别 | safe |
| 需要 Godot | 是 |
| 需要编辑器 | 否 |
| 只读 | 否 |
| 长耗时 | 否 |

## Actions

- `snapshot`
- `start`
- `stop`
- `get_data`
- `get_active_processes`
- `get_signal_connections`
- `capture_functions`

## Parameters

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `action` | enum (7 项) | ✓ | 操作类型。capture_functions(P2,2026-09-11):函数级热点——需先 run_project(profiling=true) 起 spawn 会话,一次调用完成采样窗口+排名(引擎原生 profiler 流,等价编辑器 Profiler 面板;帧级 get_data 之外的函数级 self/total 热点+最慢帧 top30) |
| `project_path` | string |  | Godot 项目目录路径（可选，默认使用 GODOT_PROJECT_PATH 环境变量或当前目录） |
| `target_fps` | number |  | 目标帧率，用于帧预算分析（get_data，默认 60） |
| `frame_count` | number |  | 采样帧数（get_data，默认 60） |
| `dimensions` | array |  | 采样维度列表（get_data，默认 ["process"]）。有效值: process, physics, nav_process |
| `leak_threshold_mb` | number |  | 内存泄漏嫌疑阈值 MB（get_data，默认 2.0） |
| `node_path` | string |  | 子树根节点路径（get_active_processes/get_signal_connections，默认 root） |
| `load_autoloads` | boolean |  | 是否加载 Autoload 上下文（默认 true） |
| `seconds` | number |  | capture_functions: 采样窗口秒数(默认 3,上限 60;窗口从首帧真实数据起算,自动停) |
| `top` | number |  | capture_functions: 返回热点行数(默认 20,上限 100,按 sort 排序) |
| `sort` | string |  | capture_functions: 排序键(selfMs|totalMs|calls,默认 selfMs) |
| `capture_limit` | number |  | capture_functions: 引擎每帧行数上限(默认 256,范围 16-512;越大覆盖函数越多开销越高) |

## 风险分布

读 7

---
<!-- AUTO-GENERATED by scripts/gen-tool-docs.mjs from capability-matrix.json v0.32.21. DO NOT edit manually; re-run npm run gen:tool-docs after tool changes. -->