Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/clearpathrobotics/cpr_gazebo/llms.txt

Use this file to discover all available pages before exploring further.

The gazebo_race_modules package is not a complete Gazebo world — it is a toolkit of modular, composable track pieces that you assemble into any custom race circuit you need. Each tile (straight segment, 90-degree corner, or barrier edge) is a standalone URDF xacro model that you spawn independently at any position and heading. By mixing tile types, surface materials, barrier styles, and sizes, you can build road, dirt, or mud tracks ranging from a compact 1 m-grid layout all the way to broad 3 m-grid circuits, without modifying a world file.

​
Tile Types

Four tile roles make up a complete track. Track tiles define the driving surface; edge tiles provide the barriers on each side.
Parameter nameDescription
straight_descriptionA straight segment of track. Spawn one or more end-to-end to form a straightaway.
corner_descriptionA 90-degree turn tile. Rotate on Z to orient the exit direction.
edge_straight_descriptionA barrier sized to border a straight tile. Place one per side of each straight.
edge_corner_descriptionA barrier sized to border a corner tile. Place one per side of each corner.
The object_descriptions.launch file loads each of these four descriptions as ROS parameters, selecting the correct URDF xacro file based on the arguments you supply. Individual tiles are then spawned by passing the appropriate parameter name to gazebo_ros/spawn_model.

​
Parameter Reference

​
track_type
string
default:"road"
The material of the driving surface. Controls which texture and mesh is loaded for straight_description and corner_description tiles.
  • road — paved asphalt surface
  • dirt — unpaved dirt surface
  • mud — muddy/off-road surface
​
barrier_type
string
default:"racing"
The appearance of the barrier edge tiles (edge_straight_description and edge_corner_description).
  • racing — standard racing barrier appearance
  • black — solid black barrier appearance
​
complexity
string
default:"simple"
Polygon density and surface resolution of all tiles. Lower complexity improves simulation performance.
  • simple — reduced polygon count; recommended for most use cases
  • complex — higher polygon count for improved visual fidelity
​
size
string
default:"small"
The footprint of each tile. All tiles in a single track must use the same size so they align correctly.
  • small — tiles are 1 m × 1 m
  • large — tiles are 3 m × 3 m

​
Launching

Bringing up a race track involves two steps: starting Gazebo with the minimal world, then loading the tile descriptions so individual tiles can be spawned.
1

Start Gazebo

Launch an empty Gazebo world configured for race modules. This also calls object_descriptions.launch with default parameters (road surface, racing barriers, simple complexity, small tiles).
roslaunch gazebo_race_modules spawn_world.launch
Optional arguments accepted by spawn_world.launch:
ArgumentDefaultDescription
use_sim_timetrueUse Gazebo simulation clock
guitrueLaunch the Gazebo GUI
headlessfalseRun without a display
world_name$(find gazebo_race_modules)/worlds/actually_empty_world.worldPath to the .world file
2

Load tile descriptions

Load the URDF xacro descriptions onto the ROS parameter server. Pass arguments to select the surface, barrier style, complexity, and tile size you want.
roslaunch gazebo_race_modules object_descriptions.launch \
  track_type:=dirt \
  barrier_type:=black \
  complexity:=simple \
  size:=large
This publishes five parameters — ground_description, straight_description, corner_description, edge_straight_description, and edge_corner_description — that your spawner nodes will reference.
3

Spawn tiles

Use gazebo_ros/spawn_model to place individual tiles at their world positions. Each tile gets a unique model name, a parameter name (-param), and a pose (-x -y -z -Y). For example:
rosrun gazebo_ros spawn_model \
  -urdf -model straight1 \
  -param straight_description \
  -x 0 -y 0 -z 0 -Y 0
Repeat for every tile in your track, rotating corner tiles as needed (-Y 1.5707, -Y 3.14159, etc.).

​
Customizing the track surface

To build a mud track with racing barriers, high-detail meshes, and small tiles: 
roslaunch gazebo_race_modules object_descriptions.launch \
  track_type:=mud \
  barrier_type:=racing \
  complexity:=complex \
  size:=small
test_small_track.launch is a fully working example that spawns a closed-loop 8-straight, 6-corner small road track with racing barriers. Study it as a reference when designing your own track layouts:
roslaunch gazebo_race_modules test_small_track.launch
The launch file accepts the same track_type, barrier_type, complexity, and size arguments, so you can try out different combinations without writing new launch XML.

​
Naming Convention

Each URDF xacro file in gazebo_race_modules/urdf/ follows a strict naming pattern that mirrors the launch argument values. Understanding the convention lets you predict the exact filename for any combination of parameters. Track tiles (driving surface): 
{size}_{track_type}_{straight|corner}_{complexity}.urdf.xacro
Edge tiles (barriers): 
{size}_{barrier_type}_edge_{straight|corner}_{complexity}.urdf.xacro
Example filenamesizetrack_type / barrier_typeTile rolecomplexity
small_road_straight_simple.urdf.xacrosmallroadstraightsimple
large_mud_corner_complex.urdf.xacrolargemudcornercomplex
small_racing_edge_straight_simple.urdf.xacrosmallracingedge straightsimple
large_black_edge_corner_complex.urdf.xacrolargeblackedge cornercomplex
All four combinations of size × track_type × {straight,corner} × complexity and size × barrier_type × {edge_straight,edge_corner} × complexity are provided, giving 24 track tile files and 16 edge tile files (plus two ground plane files).
Use complexity:=simple whenever simulation performance is a concern. The complex meshes are significantly denser and can noticeably increase physics step times, especially when many tiles are loaded simultaneously. Switch to complex only when you need higher-fidelity visuals, for example during close-up recording or demonstration runs.

Build docs developers (and LLMs) love

Get started for freeTalk to us