WWW-POSIM v0.6.16Simulator documentation
Documentation menu
WWW-POSIM / Simulator documentation

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

  1. Select ready Fixed area terrain, choose a vehicle and open the start review.
  2. Expand Edit SDF files → Download world SDF. Save a copy of world.sdf.
  3. Edit physics, lighting or the other supported fields below. Keep the terrain models, paths, world name and geographic origin.
  4. Select Upload edited world SDF. A validated revision appears in World configuration and is selected automatically.
  5. 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.

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.

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.

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.

Search documentation