# physics

> 物理系统统一工具。支持 5 种操作：raycast（3D 射线检测）、body_info（物理体碰撞信息）、diagnose（物理诊断，含速度/接触点/碰撞形状/ConcavePolygonShape3D 警告）、query_spatial（空间范围查询碰撞体）、collision_overlay（碰撞形状可视化覆盖层）。运行时操作，仅影响当前执行上下文。如需持久化，请编辑 .tscn 文件。

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

## Actions

- `raycast`
- `body_info`
- `diagnose`
- `query_spatial`
- `collision_overlay`

## Parameters

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `action` | enum (5 项) | ✓ | 操作类型：raycast | body_info | diagnose | query_spatial | collision_overlay |
| `project_path` | string |  | Godot 项目目录路径（可选，默认使用 GODOT_PROJECT_PATH 环境变量或当前目录） |
| `from` | object |  | 射线起点 {x,y,z}（raycast 必填） |
| `to` | object |  | 射线终点 {x,y,z}（raycast 必填） |
| `body_path` | string |  | 物理体节点路径（body_info / diagnose 必填） |
| `center` | object |  | 查询中心点 {x,y,z}（query_spatial 必填） |
| `radius` | number |  | 查询半径（query_spatial，默认 10.0） |
| `collision_mask` | number |  | 碰撞掩码（raycast / query_spatial 可选） |
| `exclude_paths` | array |  | 排除节点路径数组（raycast 可选） |
| `parent_path` | string |  | 父节点路径（collision_overlay，默认 root） |
| `color_override` | string |  | 统一颜色，如 "1,0,0,0.5"（collision_overlay 可选） |
| `load_autoloads` | boolean |  | 是否加载 Autoload 上下文（默认 true） |

## 风险分布

读 4 / 写 1

---
<!-- 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. -->