---
description: Gazebo 仿真的改动规则（静默失效高发区：路径/内参/接触力/描述归一化）
globs: devices/sim/**,src/arm_sim_gazebo/**
---

# 仿真改动规则

权威全文：`docs/FRAMEWORK_RULES.md` 第 4 节；平台手册：`devices/sim/gazebo/README.md`。
R4.1–R4.10 全部适用，以下是**最容易踩的几条**：

- **world 里声明任何一个 `<plugin>` 都会挤掉默认系统**（Physics / UserCommands /
  SceneBroadcaster）。少了 UserCommands，模型根本没进 Gazebo，而 `create` **仍然打印**
  `OK creation of entity`。要加插件时必须把这几个系统一起显式声明。
- **插件/资源搜索路径必须在 `ros2 launch` 之前设好**（conda 激活不会加
  `$CONDA_PREFIX/lib`）。不要绕过 `scripts/sim_env.sh` 直接 launch。
- **不许改上游描述文件**（`flexiv_description` 等）：`<mimic>` 会被 `sdformat` 丢弃、
  零质量 link 会出 NaN 惯性、无质量根 link 会连子树被丢。一律走启动时归一化。
- **gz 发的 `camera_info` 是错的**（恒为 60° 视场的默认值），内参必须按
  `cameras.yaml` 的 `horizontal_fov` 与图幅重算并覆盖。
- **深度单位**：gz 是 `32FC1` 米，真机是 `16UC1` 毫米。换算只做一次（适配器）。
- **相机 `frame_id` 必须是光学系**；`rpy` 的复合顺序是 `Rz·Ry·Rx`。
- **触觉**：轴向映射必须实测（不许从 URDF 推导）；接触布尔必须用超时判据
  （接触消息是事件式的，没有"离开"事件）；`force_scale` 决定仿真与真机能否共用阈值。
- **验收不用"有图像 / TF 查得到"**：跑 `scripts/check_sim_cameras.py` 与
  `scripts/check_sim_scene.py`（判据是物理量：反投影命中平面、像素门槛、位姿一致）。
- **停仿真用 `scripts/stop_sim_gz.sh`**，不要 `pkill -f`（会先杀掉调用它的 shell）。
  给栈里加了新进程时，记得加进该脚本的模式表 —— 它末尾会复查残留，漏项会报出来。
- **模型约定**：原点在**底面中心**、单位米、目录名 = `<model name>` =
  `model.config` 的 `<name>` = 推理类别名；碰撞体用简单几何，`visual` 可以加
  只服务于检测的细节（如工件上的亮环），但 `visual` **名字有意义**，改名字要同步改
  `sim_scene.features_from_workpiece`。