Gazebo
Treat a Gazebo simulation as a contract between world, robot, sensors,
transport, and time. Find the first contract that is not producing believable
evidence.
Start from the actual stack
- For a new robotics app or first demo, read
architect before creating worlds, launchers, or
containers. Reuse its compatible reference-app selection if already made.
Existing-world edits, simulator debugging, and explanations stay here.
- Confirm the installed
gz release, ROS distro, ros_gz pairing, render
backend, and whether the run is graphical or headless.
- When consuming an upstream simulator repository, select and pin an explicit
branch or ref compatible with that ROS distro; default HEAD is not
compatibility evidence.
- Use modern Gazebo (
gz). Gazebo Classic and libgazebo_ros_* tutorials are
a different, end-of-life stack.
- Keep upstream compatibility tables and SDF specifications as the authority
for release-sensitive package names, tags, and plugin APIs.
Trace the simulation boundary
- World: the selected world loads and the expected systems are present.
- Robot: links, joints, frames, and drive plugins agree with the physical
model and downstream interfaces.
- Sensors: rates, fields of view, ranges, noise, frames, and timestamps
model the intended hardware rather than tutorial defaults.
- Transport: prove the Gazebo topic exists before debugging its ROS bridge.
- Bridge: prefer reviewable YAML for a static bridge set. Use Python or XML
launch-based
parameter_bridge nodes when substitutions, grouping, or
vendor conventions require them; reserve ad-hoc commands for diagnosis.
- ROS: confirm
/clock, commands, odometry, transforms, and sensor messages
arrive with the expected direction and QoS.
Do not infer simulation correctness from a running process or visible GUI. A
render-backed sensor may be silent even while physics continues.
Go deeper only when needed
- For SDF worlds, models, drive plugins, spawning, and headless server mode,
read worlds and models.
- For lidar, camera, IMU, contact, noise, and rendering, read
sensors.
- For
ros_gz_bridge, topic direction, types, QoS, /clock, and frame
overrides, read the ROS 2 bridge guide.
- For a silent world, sensor, bridge, or remote launch, read
failures.
- Use the bundled SDF and bridge YAML together only as a starting pair; keep
their topic and frame names synchronized and verify syntax upstream.
Move to navigation only after the robot pose, sensor, map, and velocity
interfaces are valid. Move to ros2 when Gazebo is publishing correctly and
the fault is in the ROS graph. Use environments for container GPU/display
setup and simulation only when the simulator itself has not been chosen.
Done
- Physics time advances and the expected world and model are present.
- Every required Gazebo topic has a matching, correctly directed ROS interface.
- Sensor rate, frame, timestamp, and render output are believable.
- The run works in its intended graphical or headless environment.
- Release-specific claims match current Gazebo
and ros_gz documentation.
1---2name: gazebo3description: Build and debug modern Gazebo simulations and their ROS 2 boundary.4metadata:5 source: https://skillmd.com/skills/robium-ai/gazebo6---78# Gazebo910Treat a Gazebo simulation as a contract between world, robot, sensors,11transport, and time. Find the first contract that is not producing believable12evidence.1314## Start from the actual stack1516- For a new robotics app or first demo, read17 [architect](../architect/SKILL.md) before creating worlds, launchers, or18 containers. Reuse its compatible reference-app selection if already made.19 Existing-world edits, simulator debugging, and explanations stay here.20- Confirm the installed `gz` release, ROS distro, `ros_gz` pairing, render21 backend, and whether the run is graphical or headless.22- When consuming an upstream simulator repository, select and pin an explicit23 branch or ref compatible with that ROS distro; default HEAD is not24 compatibility evidence.25- Use modern Gazebo (`gz`). Gazebo Classic and `libgazebo_ros_*` tutorials are26 a different, end-of-life stack.27- Keep upstream compatibility tables and SDF specifications as the authority28 for release-sensitive package names, tags, and plugin APIs.2930## Trace the simulation boundary3132- **World:** the selected world loads and the expected systems are present.33- **Robot:** links, joints, frames, and drive plugins agree with the physical34 model and downstream interfaces.35- **Sensors:** rates, fields of view, ranges, noise, frames, and timestamps36 model the intended hardware rather than tutorial defaults.37- **Transport:** prove the Gazebo topic exists before debugging its ROS bridge.38- **Bridge:** prefer reviewable YAML for a static bridge set. Use Python or XML39 launch-based `parameter_bridge` nodes when substitutions, grouping, or40 vendor conventions require them; reserve ad-hoc commands for diagnosis.41- **ROS:** confirm `/clock`, commands, odometry, transforms, and sensor messages42 arrive with the expected direction and QoS.4344Do not infer simulation correctness from a running process or visible GUI. A45render-backed sensor may be silent even while physics continues.4647## Go deeper only when needed4849- For SDF worlds, models, drive plugins, spawning, and headless server mode,50 read [worlds and models](references/worlds-and-models.md).51- For lidar, camera, IMU, contact, noise, and rendering, read52 [sensors](references/sensors.md).53- For `ros_gz_bridge`, topic direction, types, QoS, `/clock`, and frame54 overrides, read [the ROS 2 bridge guide](references/ros2-bridge.md).55- For a silent world, sensor, bridge, or remote launch, read56 [failures](FAILURES.md).57- Use the bundled SDF and bridge YAML together only as a starting pair; keep58 their topic and frame names synchronized and verify syntax upstream.5960Move to `navigation` only after the robot pose, sensor, map, and velocity61interfaces are valid. Move to `ros2` when Gazebo is publishing correctly and62the fault is in the ROS graph. Use `environments` for container GPU/display63setup and `simulation` only when the simulator itself has not been chosen.6465## Done6667- Physics time advances and the expected world and model are present.68- Every required Gazebo topic has a matching, correctly directed ROS interface.69- Sensor rate, frame, timestamp, and render output are believable.70- The run works in its intended graphical or headless environment.71- Release-specific claims match current [Gazebo](https://gazebosim.org/docs/)72 and [ros_gz](https://github.com/gazebosim/ros_gz) documentation.