Custom worlds
A world SDF configures the simulation environment. Use the file exported for your selected terrain; it contains the terrain references, geographic origin and required engine systems.
Download and apply a world file
- Select ready Fixed area terrain, choose a vehicle and open the start review.
- Expand Edit SDF files → Download world SDF. Save a copy of
world.sdf. - Edit physics, lighting or the other supported fields below. Keep the terrain models, paths, world name and geographic origin.
- Select Upload edited world SDF. A validated revision appears in World configuration and is selected automatically.
- Select Start world. The saved settings are applied after terrain and vehicle preparation. Check the applied physics step, measured simulation rate and scene lighting.
A world file is linked to the terrain revision it came from. If you choose another terrain, download its file and reapply the settings. For the defaults, select Default terrain configuration. Uploads accept .world or .sdf files up to 1 MB. Fixed, ungraded worlds support this workflow; on-demand terrain and graded challenges use their assigned settings.
Supported settings
| SDF section | Settings and units |
|---|---|
physics / max_step_size |
Integration interval, 0.001–0.03 s. Smaller values increase computation. |
physics / real_time_factor |
Requested simulated time / wall time, greater than 0 and at most 10. The measured rate depends on available CPU/GPU capacity. |
gravity |
Acceleration vector in m/s². Standard gravity is 0 0 -9.81. |
magnetic_field |
World magnetic-field vector in tesla. |
scene |
Ambient light, background colour, shadows, grid and origin display. Colours use RGBA values. |
light |
Up to 32 named directional, point or spot lights: pose, direction, colour, attenuation and spot angles. Angles use radians. |
wind / linear_velocity |
Standard SDF wind velocity in m/s. Marine wave and current models have their own controls and physical interpretation. |
Use the SDFormat specification for the full schema. The upload preserves the terrain and required systems and accepts supported world settings. It does not install plugins, fetch external models or replace the geographic terrain. Configure waves and ocean current through the Scene panel; see Marine dynamics & rendering for their effect on the vehicle.
Prepared-terrain template
Download the KMOU world SDF. This complete example uses the pregenerated KMOU terrain and exposes the supported world sections. The terrain mesh and imagery remain in the terrain bundle. Download that terrain from the workspace to obtain its assets.
kmou.world
<?xml version='1.0' encoding='utf-8'?>
<sdf version="1.4">
<!--
World configuration for this terrain revision. Preserve the world name, terrain
assets, geographic origin and required systems. Upload supported environment settings
through the start review.
-->
<world name="wwos_gebco">
<!--
Scene appearance: ambient and background are RGBA colours. shadows, grid and
origin_visual control their displays. Sky settings belong to the exported scene;
upload support follows the world-settings table.
-->
<scene>
<ambient>0.01 0.01 0.01 1.0</ambient>
<sky>
<clouds>
<speed>12</speed>
</clouds>
</sky>
<shadows>1</shadows>
<background>0.7 0.8 0.9 1</background>
<grid>false</grid>
<origin_visual>false</origin_visual>
</scene>
<!--
Physics timing: max_step_size is the integration step in seconds; real_time_factor is
the requested simulated-time/wall-time ratio. The name is a label, not the step size.
Measured speed depends on available CPU/GPU capacity.
-->
<physics name="1ms" type="ignored">
<max_step_size>.02</max_step_size>
<real_time_factor>1.0</real_time_factor>
</physics>
<!--
Loaded engine plugin. filename identifies an installed library and name selects its
implementation. Preserve both when uploading numeric edits; an SDF file does not
install plugins.
-->
<!--
Runs rigid-body dynamics and contact calculations. Keep this required world system
enabled.
-->
<plugin filename="gz-sim-physics-system" name="gz::sim::systems::Physics">
</plugin>
<!--
Loaded engine plugin. filename identifies an installed library and name selects its
implementation. Preserve both when uploading numeric edits; an SDF file does not
install plugins.
-->
<!--
Provides Gazebo Transport commands for modifying the running scene. Keep this system
for workspace scene operations.
-->
<plugin filename="gz-sim-user-commands-system" name="gz::sim::systems::UserCommands">
</plugin>
<!--
Loaded engine plugin. filename identifies an installed library and name selects its
implementation. Preserve both when uploading numeric edits; an SDF file does not
install plugins.
-->
<!--
Publishes scene structure and poses so viewers can follow the simulation.
-->
<plugin filename="gz-sim-scene-broadcaster-system" name="gz::sim::systems::SceneBroadcaster">
</plugin>
<!--
Loaded engine plugin. filename identifies an installed library and name selects its
implementation. Preserve both when uploading numeric edits; an SDF file does not
install plugins.
-->
<!--
Renders camera and GPU ray sensor data. render_engine selects the installed rendering
backend; retain the exported value for your engine.
-->
<plugin filename="gz-sim-sensors-system" name="gz::sim::systems::Sensors">
<render_engine>ogre2</render_engine>
</plugin>
<!--
Loaded engine plugin. filename identifies an installed library and name selects its
implementation. Preserve both when uploading numeric edits; an SDF file does not
install plugins.
-->
<!--
World system required by custom DVL sensors. Sensor beam and tracking settings remain
in the vehicle SDF.
-->
<plugin filename="gz-sim-dvl-system" name="gz::sim::systems::DopplerVelocityLogSystem">
</plugin>
<!--
Geographic origin of this terrain. Latitude/longitude and heading are degrees;
elevation is metres. ENU means east, north, up. Preserve these values so the map,
terrain and GNSS remain aligned.
-->
<spherical_coordinates>
<surface_model>EARTH_WGS84</surface_model>
<world_frame_orientation>ENU</world_frame_orientation>
<latitude_deg>35.077175</latitude_deg>
<longitude_deg>129.085815</longitude_deg>
<elevation>0</elevation>
<heading_deg>0</heading_deg>
</spherical_coordinates>
<!--
Light source. type chooses directional, point or spot lighting; pose sets its frame
and direction its beam vector. diffuse/specular are RGBA colours; cast_shadows
controls shadow casting.
-->
<light type="directional" name="sun1">
<!--
Pose: x y z in metres, then roll pitch yaw in radians. Values use the parent frame
unless relative_to specifies another frame.
-->
<pose>50 0 150 0 0 0</pose>
<diffuse>1 1 1 1</diffuse>
<specular>.1 .1 .1 1</specular>
<direction>0.3 0.3 -1</direction>
<cast_shadows>false</cast_shadows>
</light>
<!--
Light source. type chooses directional, point or spot lighting; pose sets its frame
and direction its beam vector. diffuse/specular are RGBA colours; cast_shadows
controls shadow casting.
-->
<light type="directional" name="sun_diffuse">
<!--
Pose: x y z in metres, then roll pitch yaw in radians. Values use the parent frame
unless relative_to specifies another frame.
-->
<pose>-50 0 -150 0 0 0</pose>
<diffuse>0.6 0.6 0.6 1</diffuse>
<specular>0 0 0 1</specular>
<direction>-0.3 -0.3 -1</direction>
<cast_shadows>false</cast_shadows>
</light>
<!--
Light source. type chooses directional, point or spot lighting; pose sets its frame
and direction its beam vector. diffuse/specular are RGBA colours; cast_shadows
controls shadow casting.
-->
<light type="directional" name="sun_diffuse_1">
<!--
Pose: x y z in metres, then roll pitch yaw in radians. Values use the parent frame
unless relative_to specifies another frame.
-->
<pose>-100 500 -20 0 0 0</pose>
<diffuse>0.8 0.8 0.8 1</diffuse>
<specular>1 1 1 1</specular>
<direction>-1 -1 0</direction>
<cast_shadows>false</cast_shadows>
</light>
<!--
Light source. type chooses directional, point or spot lighting; pose sets its frame
and direction its beam vector. diffuse/specular are RGBA colours; cast_shadows
controls shadow casting.
-->
<light type="directional" name="sun_diffuse_2">
<!--
Pose: x y z in metres, then roll pitch yaw in radians. Values use the parent frame
unless relative_to specifies another frame.
-->
<pose>-150 -130 50 0 0 0</pose>
<diffuse>0.6 0.6 0.6 1</diffuse>
<specular>0.2 0.2 0.2 1</specular>
<direction>0.5 0.5 -1</direction>
<cast_shadows>false</cast_shadows>
</light>
<!--
Loaded engine plugin. filename identifies an installed library and name selects its
implementation. Preserve both when uploading numeric edits; an SDF file does not
install plugins.
-->
<plugin filename="gz-sim-buoyancy-system" name="gz::sim::systems::Buoyancy">
<!--
Layered fluid density for buoyancy, in kg/m^3. default_density applies below the
specified transition; above_depth marks the height where the density changes. Here the
boundary is z=0.
-->
<graded_buoyancy>
<default_density>1025</default_density>
<density_change>
<above_depth>0</above_depth>
<density>1</density>
</density_change>
</graded_buoyancy>
</plugin>
<!--
Model assembly: links hold rigid bodies, joints connect them, and plugins provide
simulation behavior. Keep model, link and joint names consistent with the exported
controllers.
-->
<model name="gebco_terrain">
<!--
Static models stay fixed instead of moving under gravity or contact forces. The
terrain is static; vehicle links remain dynamic.
-->
<static>true</static>
<!--
Rigid body and its local coordinate frame. Geometry, mass properties and sensors
inside this link move together.
-->
<link name="terrain">
<!--
Contact geometry used by physics. Keep dimensions and placement consistent with the
hull; a simplified shape reduces collision computation.
-->
<collision name="gebco_collision">
<geometry>
<!--
Mesh resource and optional axis scale. Keep the exported asset path and bundle
together; scale multiplies the mesh coordinates.
-->
<mesh>
<uri>terrain.dae</uri>
</mesh>
</geometry>
</collision>
<!--
Visible surface for rendering and cameras. Changing a visual does not automatically
resize the collision shape or change mass.
-->
<visual name="seabed">
<geometry>
<!--
Mesh resource and optional axis scale. Keep the exported asset path and bundle
together; scale multiplies the mesh coordinates.
-->
<mesh>
<uri>terrain-visual.dae</uri>
</mesh>
</geometry>
<!--
Surface appearance. RGBA colours and PBR texture maps affect rendering. Keep terrain
texture paths with the exported assets; material settings do not change mass or
friction automatically.
-->
<material>
<ambient>0.6 0.6 0.6 1</ambient>
<diffuse>1 1 1 1</diffuse>
<specular>0.03 0.03 0.03 1</specular>
<pbr>
<metal>
<albedo_map>/home/docker/wwos-data/terrain/fd128f89b979e7830a34dcd7/seabed-sand-diff-1803d7e2861b304b.jpg</albedo_map>
<roughness>1</roughness>
<normal_map>/home/docker/wwos-data/terrain/fd128f89b979e7830a34dcd7/seabed-sand-nor_gl-0f35185b7225fe20.jpg</normal_map>
<roughness_map>/home/docker/wwos-data/terrain/fd128f89b979e7830a34dcd7/seabed-sand-rough-318b440c109de741.jpg</roughness_map>
<metalness>0</metalness>
</metal>
</pbr>
</material>
</visual>
<!--
Visible surface for rendering and cameras. Changing a visual does not automatically
resize the collision shape or change mass.
-->
<visual name="land">
<geometry>
<!--
Mesh resource and optional axis scale. Keep the exported asset path and bundle
together; scale multiplies the mesh coordinates.
-->
<mesh>
<uri>terrain-visual-land.dae</uri>
</mesh>
</geometry>
<!--
Surface appearance. RGBA colours and PBR texture maps affect rendering. Keep terrain
texture paths with the exported assets; material settings do not change mass or
friction automatically.
-->
<material>
<ambient>0.6 0.6 0.6 1</ambient>
<diffuse>1 1 1 1</diffuse>
<specular>0.03 0.03 0.03 1</specular>
<pbr>
<metal>
<albedo_map>/home/docker/wwos-data/terrain/fd128f89b979e7830a34dcd7/land-satellite-eb6fd1423859d847a276a4db49db6db51a61fe8965171639c94f8d3df66e0199.png</albedo_map>
<roughness>1</roughness>
<metalness>0</metalness>
</metal>
</pbr>
</material>
</visual>
</link>
</model>
<!--
Loaded engine plugin. filename identifies an installed library and name selects its
implementation. Preserve both when uploading numeric edits; an SDF file does not
install plugins.
-->
<plugin filename="gz-sim-imu-system" name="gz::sim::systems::Imu" />
<!--
Loaded engine plugin. filename identifies an installed library and name selects its
implementation. Preserve both when uploading numeric edits; an SDF file does not
install plugins.
-->
<plugin filename="gz-sim-magnetometer-system" name="gz::sim::systems::Magnetometer" />
<!--
World gravity vector x y z in m/s^2. Negative z points down in this ENU world.
-->
<gravity>0 0 -9.81</gravity>
<!--
World magnetic-field vector x y z in tesla, used by magnetometer simulation.
-->
<magnetic_field>5.64e-6 2.29e-5 -4.2e-5</magnetic_field>
<!--
Standard SDF wind velocity in m/s. A force model must use this value to affect motion.
Configure marine waves and currents through their own scene controls.
-->
<wind>
<linear_velocity>0 0 0</linear_velocity>
</wind>
</world>
</sdf>
This example is exported from the Linux engine. Use your host’s export, especially on macOS, so plugin libraries match the installed runtime.
Use terrain you generated
Generate and select your own terrain, then download World SDF at the start review. This exports the correct model paths and geographic origin for that terrain. Apply the same physics or lighting edits to this file rather than replacing the terrain paths in the KMOU example.
To keep a portable copy, download the selected terrain’s ZIP and retain the world file beside its relative assets. The application upload applies settings to the matching saved terrain; it does not upload the ZIP’s terrain through the world-SDF control. Use the terrain preparation workflow to create or restore the terrain first.
Compare before a longer run
Start with the same vehicle, spawn position and sensor selection for both tests. Check the applied time step, measured realtime ratio, light direction, cameras and vehicle motion. A faster requested factor does not guarantee faster rendering or sensor delivery. Save your original file so you can select the default configuration or upload an earlier copy.
Performance and display settings
Simulation time
Real-time factor (RTF) measures simulated seconds per wall second. Requested rate is a target. An RTF below 1 means execution is slower than real time under the current load.
- Physics step: affects contact, waves, sensor timing and control stability
- Network delay: affects commands and display delivery
- Above 1×: live AIS hidden
- Display updates: limited by camera rate
After changing the physics step, check stationary motion, turns, clearance, diving and return with both built-in robots.
Camera and graphics
Reduce unnecessary camera rates and resolution first.
| View | Renderer |
|---|---|
| Sensor images | Gazebo on the engine host |
| Personal Vehicle / World, Browser selected | Browser GPU |
| Personal Vehicle / World, Gazebo selected | Gazebo on the engine host; installed-app default |
| Public LIVE Vehicle / World | Gazebo observation cameras |
Browser lighting controls sky, reflection, tone mapping and water normals. Wave geometry uses samples from the physical solver.
Compare Graphics diagnostics in the same scene.
- FPS and 95th-percentile frame time (p95)
- Draw calls and triangles
- Texture and geometry use
Moving terrain automatically reduces distant visual geometry through Terrain LOD: detail near the vehicle. Collision and sensor processing have separate costs. Selecting the Browser scene still leaves robot cameras and GPU LiDAR in Gazebo. Compare video FPS, sensor Hz and physical RTF separately.
Hardware sizing
Compare equipment with the same world, robot, sensor rates and target speed. Start with one session and increase session count. Include terrain-preparation spikes.
- Median RTF and 5th percentile
- Physics step time
- Camera reception rate and sample age
- CPU and memory
- GPU utilization and VRAM
Gazebo physics depends on per-core performance; terrain and sensors also use multiple cores. Camera count and resolution increase GPU load. Public voyage viewers share one world.
Apple Silicon uses Metal. Ubuntu and Windows/WSL Docker engines require drivers and runtimes compatible with their images.
Usage time and storage
Public LIVE uses no personal allowance. Models, uploads and caches have account storage limits. Reserve disk space for engine and model downloads. See Account and usage time.