add support for managing simulation worlds (back-port #4)

ayushgnv · peci1 · adamdbrw · zakmat · commit 63a5e914cf33 · 2025-08-13T10:44:40.000+02:00
Co-authored-by: Martin Pecka &lt;peci1@seznam.cz&gt;
Co-authored-by: Adam Dąbrowski &lt;adam.dabrowski@robotec.ai&gt;
Co-authored-by: Mateusz Żak &lt;mateusz.zak@robotec.ai&gt;
Signed-off-by: Mateusz Żak &lt;mateusz.zak@robotec.ai&gt;
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -23,15 +23,19 @@ set(msg_files
     "msg/EntityInfo.msg"
     "msg/EntityState.msg"
     "msg/NamedPose.msg"
+    "msg/Resource.msg"
     "msg/Result.msg"
     "msg/SimulationState.msg"
     "msg/SimulatorFeatures.msg"
     "msg/Spawnable.msg"
     "msg/TagsFilter.msg"
+    "msg/WorldResource.msg"
 )
 
 set(srv_files
     "srv/DeleteEntity.srv"
+    "srv/GetAvailableWorlds.srv"
+    "srv/GetCurrentWorld.srv"
     "srv/GetEntities.srv"
     "srv/GetEntitiesStates.srv"
     "srv/GetEntityBounds.srv"
@@ -42,12 +46,14 @@ set(srv_files
     "srv/GetSimulationState.srv"
     "srv/GetSimulatorFeatures.srv"
     "srv/GetSpawnables.srv"
+    "srv/LoadWorld.srv"
     "srv/ResetSimulation.srv"
     "srv/SetEntityInfo.srv"
     "srv/SetEntityState.srv"
     "srv/SetSimulationState.srv"
     "srv/SpawnEntity.srv"
     "srv/StepSimulation.srv"
+    "srv/UnloadWorld.srv"
 )
 
 set(action_files
diff --git a/README.md b/README.md
@@ -11,7 +11,7 @@ service mechanism itself.
 
 ## Suggested interface implementation priorities
 
-[GetSimulatorFeatures](msg/GetSimulationFeatures.msg) should be implemented first, as it provides users with information about
+[GetSimulatorFeatures](srv/GetSimulatorFeatures.srv) should be implemented first, as it provides users with information about
 the state of support for all standard simulation interfaces.
 
 Following that, aim for maintaining consistency within the implemented feature, such as enabling both
@@ -22,4 +22,9 @@ Some interfaces represent optional utility and are considered lower priority:
 - [GetNamedPoseBounds](srv/GetNamedPoseBounds.srv)
 - [GetNamedPoses](srv/GetNamedPoses.srv)
 - [GetSpawnables](srv/GetSpawnables.srv)
-- [SetEntityInfo](srv/SetEntityInfo.srv)
+- [SetEntityInfo](srv/SetEntityInfo.srv)
+- [GetAvailableWorlds](srv/GetAvailableWorlds.srv)
+- [LoadWorld](srv/LoadWorld.srv)
+- [UnloadWorld](srv/UnloadWorld.srv)
+- [GetCurrentWorld](srv/GetCurrentWorld.srv)
+
diff --git a/msg/Resource.msg b/msg/Resource.msg
@@ -0,0 +1,7 @@
+# This message is used to specify a resource, either by a URI or by its string content.
+
+string uri              # If uri field is empty, resource_string must not be empty.
+
+string resource_string  # An entity definition file passed as a string, only used if uri is empty.
+                        # If uri field is not empty, resource_string field will be ignored.
+                        # Simulators may support spawning from a file generated on the fly (e.g. XACRO).
diff --git a/msg/SimulationState.msg b/msg/SimulationState.msg
@@ -1,16 +1,24 @@
 # Simulation states used in SetSimulationState and returned in GetSimulationState
 
-uint8 STATE_STOPPED      = 0           # Simulation is stopped, which is equivalent to pausing and resetting with ALL.
-                                       # This is typically the default state when simulator is launched.
-                                       # Stopped simulation can be played. It can also be paused, which means
-                                       # starting simulation in a paused state immediately,
-                                       # without any time steps for physics or simulated clock ticks.
-uint8 STATE_PLAYING      = 1           # Simulation is playing, can be either paused or stopped.
-uint8 STATE_PAUSED       = 2           # Simulation is paused, can be either stopped (which will reset it) or played.
-uint8 STATE_QUITTING     = 3           # Closing the simulator application. Switching from STATE_PLAYING or STATE_PAUSED
-                                       # states is expected to stop the simulation first, and then exit.
-                                       # Simulation interfaces will become unavailable after quitting.
-                                       # Running simulation application is outside of the simulation interfaces as
-                                       # there is no service to handle the call when the simulator is not up.
+uint8 STATE_STOPPED          = 0           # Simulation is stopped, which is equivalent to pausing and resetting with ALL_PAUSED.
+                                           # This is typically the default state when simulator is launched.
+                                           # Stopped simulation can be played. It can also be paused, which means
+                                           # starting simulation in a paused state immediately,
+                                           # without any time steps for physics or simulated clock ticks.
 
+uint8 STATE_PLAYING          = 1           # Simulation is playing, can be either paused or stopped.
+
+uint8 STATE_PAUSED           = 2           # Simulation is paused, can be either stopped (which will reset it) or played.
+
+uint8 STATE_QUITTING         = 3           # Closing the simulator application. Switching from STATE_PLAYING or STATE_PAUSED
+                                           # states is expected to stop the simulation first, and then exit.
+                                           # Simulation interfaces will become unavailable after quitting.
+                                           # Running simulation application is outside of the simulation interfaces as
+                                           # there is no service to handle the call when the simulator is not up.
+
+uint8 STATE_NO_WORLD         = 4           # Simulation world is currently unloaded.
+                                           # The simulation is inactive and cannot be started, stopped, or paused.
+
+uint8 STATE_LOADING_WORLD    = 5           # Simulation world is currently loading.
+                                           # The simulation is inactive while world is loading and cannot be started, stopped, or paused.
 uint8 state
diff --git a/msg/SimulatorFeatures.msg b/msg/SimulatorFeatures.msg
@@ -31,6 +31,12 @@ uint8 STEP_SIMULATION_MULTIPLE  = 32      # Supports multi-stepping through simu
                                           # service or through SimulateSteps action.
 uint8 STEP_SIMULATION_ACTION    = 33      # Supports SimulateSteps action interface.
 
+uint8 WORLD_LOADING             = 40      # Supports LoadWorld interface
+uint8 WORLD_RESOURCE_STRING     = 41      # Supports LoadWorld resource_string field
+uint8 WORLD_TAGS                = 42      # Supports world tags and tag filtering
+uint8 WORLD_UNLOADING           = 43      # Supports UnloadWorld interface
+uint8 WORLD_INFO_GETTING        = 44      # Supports GetCurrentWorld interface
+uint8 AVAILABLE_WORLDS          = 45      # Supports GetAvailableWorlds interface
 
 uint16[] features                         # A list of simulation features as specified by the list above.
 
diff --git a/msg/Spawnable.msg b/msg/Spawnable.msg
@@ -1,5 +1,9 @@
 # Robot or other object which can be spawned in simulation runtime.
 
-string uri                                # URI which will be accepted by SpawnEntity service.
+string uri                                # Resource such as SDFormat, URDF, USD or MJCF file, a native prefab, etc.
+                                          # Valid URIs can be determined by calling GetSpawnables first, and you can check
+                                          # the simulator format support by reading SimulatorFeatures spawn_formats field.
+
 string description                        # Optional description for the user, e.g. "robot X with sensors A,B,C".
+
 Bounds spawn_bounds                       # Optional spawn area bounds which fully encompass this object.
diff --git a/msg/WorldResource.msg b/msg/WorldResource.msg
@@ -0,0 +1,15 @@
+# World is a virtual environment in which the simulation happens.
+# Worlds are also known as scenes or levels in some simulators.
+# Depending on the world format, loading of a world might be associated with changes
+# in certain parameters, including physics settings such as gravity.
+# World resources may be defined in standard or simulation-specific formats,
+# and, depending on the simulator, loaded from local or remote repositories.
+
+
+string name                               # World name, which is not necessarily unique.
+
+Resource world_resource                   # The resource for the world to be loaded.
+
+string description                        # Optional custom description of the world
+
+string[] tags                             # Optional tags describing the world (e.g., "indoor", "outdoor", "warehouse")
diff --git a/package.xml b/package.xml
@@ -2,7 +2,7 @@
 <?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>simulation_interfaces</name>
-  <version>1.0.1</version>
+  <version>1.1.0</version>
   <description>A package containing simulation interfaces including messages, services and actions</description>
   <maintainer email="adam.dabrowski@robotec.ai">Adam Dabrowski</maintainer>
   <license>Apache License 2.0</license>
diff --git a/srv/GetAvailableWorlds.srv b/srv/GetAvailableWorlds.srv
@@ -0,0 +1,23 @@
+# Return a list of available world resources which can be used with LoadWorld.
+# Support for this interface is indicated through the AVAILABLE_WORLDS value in GetSimulatorFeatures.
+# By default, a simulator will search its default local and online sources. If some
+# default sources can't be accessed (e.g. due to connectivity issues), the
+# DEFAULT_SOURCES_FAILED error result code will be returned.
+
+string[] additional_sources             # Optional field for additional sources (local or remote) to search,
+                                        # specified as standard URIs if possible.
+
+TagsFilter filter                       # Only get worlds with tags matching the filter. The filter is optional and matches everything by default.
+                                        # This feature is supported if WORLD_TAGS feature is included in output of GetSimulatorFeatures.
+
+bool offline_only                       # If true, only offline/local sources should be searched. Defaults to false.
+
+bool continue_on_error                  # If true, the simulator will continue to search sources even if some fail.
+                                        # The service will return success if any source yielded worlds. Defaults to false.
+---
+
+uint8 DEFAULT_SOURCES_FAILED = 101      # Some default sources could not be accessed.
+
+Result result                           # Standard result message. A specific result code should be used if some sources were not accessible.
+
+WorldResource[] worlds                  # Available world resources.
diff --git a/srv/GetCurrentWorld.srv b/srv/GetCurrentWorld.srv
@@ -0,0 +1,10 @@
+# Get information about the currently loaded world in the simulation.
+# Support for this interface is indicated through the WORLD_INFO_GETTING value in GetSimulatorFeatures.
+
+---
+
+uint8 NO_WORLD_LOADED = 101     # No world is loaded at the moment.
+
+Result result                   # Standard result message
+
+WorldResource world             # Information about the currently loaded world. Only valid if result is RESULT_OK.
diff --git a/srv/LoadWorld.srv b/srv/LoadWorld.srv
@@ -0,0 +1,29 @@
+# Load a simulation world from a file or resource.
+# This means clearing the current scene (removing all entities), loading the new world and setting the simulation to the stopped state.
+# Support for this interface is indicated through the WORLD_LOADING value in GetSimulatorFeatures.
+# resource_string field support is indicated through the WORLD_RESOURCE_STRING value in GetSimulatorFeatures.
+# Currently loaded worlds will be unloaded before attempting to load a new one.
+# Any previously spawned entities will be removed. Once a world is loaded, simulation will be left in a Stopped state.
+
+string uri                                  # Resource such as SDF, USD, MJCF, or other simulator-native format world file.
+
+string resource_string                      # Simulation world passed as a string. This field is used if the uri field is empty.
+
+bool fail_on_unsupported_element            # Fail on unsupported elements (such as SDFormat sub-tags). By default, such elements are ignored.
+
+
+bool ignore_missing_or_unsupported_assets   # Ignore missing or unsupported assets. By default, missing or unsupported assets result in failure.
+
+---
+
+uint8 UNSUPPORTED_FORMAT = 101              # Format for uri or resource string is unsupported.
+uint8 NO_RESOURCE = 102                     # Both uri and resource string are empty.
+uint8 RESOURCE_PARSE_ERROR = 103            # Resource file or string failed to parse.
+uint8 MISSING_ASSETS = 104                  # At least one of resource assets (such as meshes) was not found.
+uint8 UNSUPPORTED_ASSETS = 105              # At least one of resource assets (such as meshes) is not supported.
+uint8 UNSUPPORTED_ELEMENTS = 106            # At least one of world definition elements such as format tags is unsupported.
+
+
+Result result                               # Standard result message
+
+WorldResource world                         # Information about the loaded world. Only valid if result is RESULT_OK.
diff --git a/srv/UnloadWorld.srv b/srv/UnloadWorld.srv
@@ -0,0 +1,9 @@
+# Unload the current simulation world.
+# Support for this interface is indicated through the WORLD_UNLOADING value in GetSimulatorFeatures.
+# Any previously spawned entities will be removed.
+
+---
+
+uint8 NO_WORLD_LOADED = 101      # No world is loaded at the moment.
+
+Result result # Standard result message
