suggested changes to simulation interface worlds

msg/SimulatorFeatures.msg

@@ -32,10 +32,11 @@ uint8 STEP_SIMULATION_MULTIPLE  = 32      # Supports multi-stepping through simu
 uint8 STEP_SIMULATION_ACTION    = 33      # Supports SimulateSteps action interface.
 
 uint8 WORLD_LOADING             = 40      # Supports LoadWorld interface
-uint8 WORLD_LOADING_RESOURCE_STRING = 41  # Supports LoadWorld resource_string field
-uint8 WORLD_UNLOADING           = 42      # Supports UnloadWorld interface
-uint8 WORLD_INFO_GETTING        = 43      # Supports GetCurrentWorld interface
-uint8 AVAILABLE_WORLDS          = 44      # Supports GetAvailableWorlds 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.
 

msg/WorldResource.msg

@@ -1,16 +1,18 @@
-# World resource that can be loaded into the simulation
+# 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. 
 
-# World name
+# World name, which is not necessarily unique.
 string name
 
-# URI which will be accepted by LoadWorld service
+# URI which will be accepted by LoadWorld service, unique per world.
 string uri
 
 # Optional description of the world
 string description
 
 # Optional tags describing the world (e.g., "indoor", "outdoor", "warehouse")
 string[] tags
-
-# Whether this is the simulator's default/initial world
-bool is_default 

srv/GetAvailableWorlds.srv

@@ -1,12 +1,18 @@
-# Return a list of available world resources which are valid as LoadWorld uri fields
-#
+# 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.
 
-# Optional field for additional sources (local or remote) to search
+# Optional field for additional sources (local or remote) to search, 
+# specified as standard URIs if possible.
 string[] sources
+
+# Only get worlds with tags matching the filter. The filter is optional and none by default.
+# This feature is supported if WORLD_TAGS feature is included in output of GetSimulatorFeatures.
+TagsFilter filter
+
 ---
+
 # Standard result message
-simulation_interfaces/Result result
+Result result
 
-# Available world resources with URI and additional information
-simulation_interfaces/WorldResource[] worlds 
+# Available world resources.
+WorldResource[] worlds 

srv/GetCurrentWorld.srv

@@ -1,10 +1,12 @@
-# Get information about the currently loaded world in the simulation
-#
+# 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.
+
 # Standard result message
-simulation_interfaces/Result result
+Result result
 
-# Information about the currently loaded world
-simulation_interfaces/WorldResource world 
+# Information about the currently loaded world. Only valid if result is RESULT_OK.
+WorldResource world 

srv/LoadWorld.srv

@@ -1,28 +1,29 @@
-# Load a simulation world from a file or resource
-#
+# Load a simulation world from a file or resource.
 # Support for this interface is indicated through the WORLD_LOADING value in GetSimulatorFeatures.
-# Support for the resource_string field is indicated through the WORLD_LOADING_RESOURCE_STRING 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.
 
-# Existing worlds will be unloaded before attempting to load a new one.
-
-# Resource such as SDF, URDF, USD, or MJCF world file
+# Resource such as SDF, URDF, USD, MJCF, or other simulator-native format world file.
 string uri
 
-# World definition passed as a string
+# Simulation world passed as a string. This field is used if the uri field is empty.
 string resource_string
 
-# If true, existing entities will be cleared before loading the new world
-bool clear_entities
+# Fail on unsupported elements (such as SDFormat sub-tags). By default, such elements are ignored.
+bool fail_on_unsupported_element
+
+# Ignore missing or unsupported assets. By default, missing or unsupported assets result in failure.
+bool ignore_missing_or_unsupported_assets
+
 ---
-# Error Codes
-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 
 
-# Standard result message
-simulation_interfaces/Result result
+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.
 
-# Information about the loaded world
-simulation_interfaces/WorldResource world
+# Standard result message
+Result result

srv/UnloadWorld.srv

@@ -1,9 +1,10 @@
-# Unload the current simulation world
-#
+# 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.
 
-# If true, existing dynamically spawned entities will remain
-bool keep_entities
 ---
+
+uint8 NO_WORLD_LOADED = 101      # No world is loaded at the moment.
+
 # Standard result message
-simulation_interfaces/Result result 
+Result result