Proposal to add support for managing simulation worlds #4

ayushgnv · 2025-04-01T21:36:06Z

Proposal for World Management Services for Simulation Interfaces Standard

These interfaces provide standardized world management across simulation_interfaces.

The proposed API introduces functionality to dynamically load and unload worlds, enabling automated testing across diverse simulation environments without restarting the simulator. This would allow for workflows where users can load a world file, spawn entities, and run SIL testing facilitating continuous operation on remote systems (sometimes in headless mode).

For Isaac Sim and O3DE (@adamdbrw), these services would likely be useful as these platforms support loading worlds dynamically.

Unlike Entities only one world should be loaded at a time. Attempting to load a world when a world already exists should result in automatically unloading the previously loaded world before loading the current one.

Change Summary:

New message: WorldResource
New services: LoadWorld, UnloadWorld, GetCurrentWorld, GetAvailableWorlds
Added corresponding feature flags (40-44) to SimulatorFeatures.msg
Added world_formats field to track supported world file formats

pijaro · 2025-04-08T07:57:16Z

I think it's a good idea.

However, I'm missing an additional simulator state. Setting up a new world will take time, and we should consider that. I suggest adding something like this to SimulationState.msg:

uint8 STATE_INITIALIZING = 4  # Simulation resources are being loaded; the simulation is not running and cannot be started, stopped, or paused.

adamdbrw · 2025-04-09T14:23:18Z

Good PR, I would love to follow up and propose changes soon, will submit as a PR targeting this one.

ayushgnv · 2025-04-11T02:50:42Z

I think it's a good idea.

However, I'm missing an additional simulator state. Setting up a new world will take time, and we should consider that. I suggest adding something like this to SimulationState.msg:
uint8 STATE_INITIALIZING = 4  # Simulation resources are being loaded; the simulation is not running and cannot be started, stopped, or paused.

@pijaro Thanks, great idea! Added STATE_INITIALIZING to SimulationState.msg

adamdbrw · 2025-04-17T14:07:26Z

ayushgnv#1 - there's the PR

adamdbrw · 2025-04-24T08:52:52Z

@mjcarroll @peci1 @DLu could you take a look at this one?

peci1

I went through this and left a few comments.

srv/LoadWorld.srv

msg/SimulationState.msg

srv/GetAvailableWorlds.srv

srv/LoadWorld.srv

mjcarroll · 2025-05-12T12:53:30Z

@peci1 any more feedback here or are we good?

DLu

Apologies for the late review.

The thing that confuses me is what actually goes in the URI. I imagined them as unique ids, but LoadWorld.srv specifies them as having a specific format, like SDF.

DLu · 2025-05-12T20:05:57Z

msg/SimulationState.msg

+uint8 STATE_NO_WORLD     = 4           # Simulation world is currently unloaded and a new world has not finished loading yet.
+                                       # The simulation is inactive and cannot be started, stopped, or paused.


I feel like NO_WORLD is a little too specific in this context and STATE_TRANSITIONAL would be better.

Suggested change

uint8 STATE_NO_WORLD = 4 # Simulation world is currently unloaded and a new world has not finished loading yet.

# The simulation is inactive and cannot be started, stopped, or paused.

uint8 STATE_NO_WORLD = 4 # Simulation world is currently unloaded, and/or a new world has not finished loading yet.

# The simulation is inactive and cannot be started, stopped, or paused.

I'm not 100% sure with my English here. Would TRANSITIONAL also semantically cover the instant where no world is loaded and no world is commanded to be loading?

@peci1 I think STATE_TRANSITIONAL should work as it indicates that simulation is not ready.

I think simulation should not be running anyway if a world is not present. Therefore STATE_TRANSITIONAL does indicate that simulator is not ready.

Alternatively we could switch to STATE_WORLD_UNLOADED. @peci1 @DLu what do you think?

I still have a problem with the word transitional. It evokes that a transition is happening. But sometimes, the simulation can just have no world and no transition to execute.

@peci1 I see your point. However I think we are trying to enforce the idea that having no world being loaded means simulation cannot be run and simulation should be in limbo until a new world is loaded.

In my mind an empty void is simply an "empty world" thats been loaded. Which is why I think its ok to call it TRANSITIONAL? This would be a state on its own, and not combined with PLAY, PAUSE, STOP, QUITTING.

Would STATE_LOADING_WORLD work instead?

I don't see "no world" equal to "empty world". A world is not only a collection of spawnables. It is also something that defines the gravitational field, magnetic field, mapping between world and spherical coordinates, wind, atmospheric pressure, time reference and many other things.

So you cannot spawn entities in "no world".

Gazebo is written in a way that (at least theoretically) allows having a running gz-server without a loaded world, or with multiple worlds loaded at once, or with multiple worlds loaded sequentially.

So the running server with no loaded world would have the state NO_WORLD.

I see the value of both NO_WORLD and LOADING_WORLD states.

I don't think there is harm in having both NO_WORLD and LOADING_WORLD states. I think it is easy enough to set on the simulator side. Maybe that would be a good patch?

@adamdbrw @peci1 @DLu added both sates in the SimulationState message here: https://github.com/ros-simulation/simulation_interfaces/pull/4/files#diff-1458e48779d6769bbb6b839651ff4efa24ae07fbc0cbb757dc8a90458b2b7f34:~:text=uint8%20STATE_NO_WORLD%20%20%20%20%20%20%20%20%20%3D%204%20%20%20%20%20%20%20%20%20%20%20%23%20Simulation%20world%20is%20currently%20unloaded,loading%20and%20cannot%20be%20started%2C%20stopped%2C%20or%20paused.

msg/WorldResource.msg

DLu · 2025-05-12T20:14:27Z

srv/LoadWorld.srv

+string uri
+
+# Simulation world passed as a string. This field is used if the uri field is empty.
+string resource_string


Would it make more sense to have two separate services.

Add World, which takes in a resource_string and makes it available for use

Load World, which only takes a uri

Would does "makes it available for use" entail for the simulator? Is there any pre-processing that needs to happen before loading a world in your case?

Does "adding" have a value from the perspective of external interface node / automation? I am of opinion that it is an implementation detail, some resources need to be downloaded and other will be available; I would expect the simulator to handle that.

Perhaps it would be useful to document that loading can take a bit and make things clearer through error codes, suggesting async service call etc, what do you think?

So from an abstract perspective, here's what I imagine.

As an external client, I call GetAvailableWorlds.srv and get a list of unique world uri.

worlds: [ - {uri: 'factory1'} - {uri: 'competition_2'} - {uri: 'moon} ]

I could then call LoadWorld.srv with uri: 'moon'. However, if instead I wanted to load in some other world that is not specified yet, I could call AddWorld.srv with the resource_string (which I assume would be SDF or similar), and then that new world be listed in the available worlds.

The core issue here is that I think it is semantically cleaner to run separate Add/Load calls than it is to have the single Load call with different behavior if the uri field is empty or not. Also, what happens when uri is nonempty and resource_string is nonempty?

It seems to me it could be beneficial to create a Resource message like this:

string uri string resource_string # only used if uri is empty

This could then be used in Spawnable, WorldResource and here.

The proposal with AddWorld/LoadWorld seems too complicated to me.

@peci1 @adamdbrw Added Resource message and updated Spawnables and WorldResource

ayushgnv · 2025-05-13T05:50:42Z

Apologies for the late review.

The thing that confuses me is what actually goes in the URI. I imagined them as unique ids, but LoadWorld.srv specifies them as having a specific format, like SDF.

@DLu At least from an Isaac Sim perspective we would load USD files by accessing the filepaths in the URI field. Happy to update the LoadWorld.srv message type or description to be something more permissive.

DLu · 2025-05-13T16:24:59Z

Apologies for the late review.
The thing that confuses me is what actually goes in the URI. I imagined them as unique ids, but LoadWorld.srv specifies them as having a specific format, like SDF.

@DLu At least from an Isaac Sim perspective we would load USD files by accessing the filepaths in the URI field. Happy to update the LoadWorld.srv message type or description to be something more permissive.

Might just be me, but I could benefit from a description of how you envision these services being used, similar to the "call this one, then this one" example I gave above.

msg/WorldResource.msg

srv/GetAvailableWorlds.srv

peci1 · 2025-05-14T21:01:39Z

msg/SimulationState.msg

+uint8 STATE_NO_WORLD     = 4           # Simulation world is currently unloaded and a new world has not finished loading yet.
+                                       # The simulation is inactive and cannot be started, stopped, or paused.


I'm not 100% sure with my English here. Would TRANSITIONAL also semantically cover the instant where no world is loaded and no world is commanded to be loading?

peci1 · 2025-05-14T21:05:58Z

srv/LoadWorld.srv

+string uri
+
+# Simulation world passed as a string. This field is used if the uri field is empty.
+string resource_string


It seems to me it could be beneficial to create a Resource message like this:

string uri string resource_string # only used if uri is empty

This could then be used in Spawnable, WorldResource and here.

The proposal with AddWorld/LoadWorld seems too complicated to me.

adamdbrw · 2025-06-27T14:13:43Z

msg/Resource.msg

@@ -0,0 +1,5 @@
+# This message is used to specify a resource, either by a URI or by its string content.


This seems to be applied to Spawnable, but not to SpawnEntity interface.
Both of these changes are breaking currently released interfaces. I am not opposed to having a quick version uptick for the package with Worlds feature in though.

Thanks for catching! Applied it to SpawnEntity as well.

Bumped the version to 2.0.0 due to the breaking changes

Signed-off-by: Adam Dąbrowski <adam.dabrowski@robotec.ai>

Co-authored-by: Martin Pecka <peci1@seznam.cz>

Co-authored-by: Adam Dąbrowski <adam.dabrowski@robotec.ai>

…ulationState

Co-authored-by: Adam Dąbrowski <adam.dabrowski@robotec.ai>

Update sources field to additional_sources Co-authored-by: Martin Pecka <peci1@seznam.cz>

ayushgnv changed the title ~~Proposal to add support for modifying simulation worlds~~ Proposal to add support for managing simulation worlds Apr 1, 2025

adamdbrw approved these changes Apr 24, 2025

View reviewed changes

peci1 suggested changes May 1, 2025

View reviewed changes

adamdbrw reviewed May 5, 2025

View reviewed changes

srv/LoadWorld.srv Show resolved Hide resolved

ayushgnv requested a review from peci1 May 6, 2025 10:59

mjcarroll approved these changes May 12, 2025

View reviewed changes

DLu reviewed May 12, 2025

View reviewed changes

peci1 reviewed May 14, 2025

View reviewed changes

ayushgnv requested review from peci1, adamdbrw and DLu June 27, 2025 06:31

adamdbrw reviewed Jun 27, 2025

View reviewed changes

adamdbrw approved these changes Jun 27, 2025

View reviewed changes

ayushgnv force-pushed the simulation_world branch from 1da4d58 to eaefa31 Compare June 27, 2025 19:56

ayushgnv and others added 8 commits June 30, 2025 21:37

Added new interfaces for simulation worlds

9997b6c

Fix formatting

8dbbf05

Updated descriptions

7d109c6

Added STATE_INITIALIZING in SimulationState.msg

7d05855

suggested changes to simulation interface worlds

c4f5ec6

Signed-off-by: Adam Dąbrowski <adam.dabrowski@robotec.ai>

Applied review remarks + added extra feature field

90dab29

Signed-off-by: Adam Dąbrowski <adam.dabrowski@robotec.ai>

Update srv/GetAvailableWorlds.srv

cb5ff48

Co-authored-by: Martin Pecka <peci1@seznam.cz>

Update srv/LoadWorld.srv

fdc0537

Co-authored-by: Martin Pecka <peci1@seznam.cz>

ayushgnv and others added 13 commits June 30, 2025 21:37

Removed urdf mention in LoadWorld service

d0b5ece

Update srv/LoadWorld.srv

e1a3044

Co-authored-by: Adam Dąbrowski <adam.dabrowski@robotec.ai>

Added WorldResource in LoadWorld and renamed to STATE_NO_WORLD in Sim…

1a43d33

…ulationState

Fix formatting

e9f04a3

Update msg/SimulationState.msg

df77fa1

Co-authored-by: Adam Dąbrowski <adam.dabrowski@robotec.ai>

Update srv/GetAvailableWorlds.srv

f036645

Update sources field to additional_sources Co-authored-by: Martin Pecka <peci1@seznam.cz>

Added Resource message type

04962fc

Populate resource msgs with new Resource msg type

dcdbdb8

Added Loading World state

45ab916

Fixed formatting and updated the world services

2b0a5c1

Updated documentation for Resource message

de3ad42

Update Spawn Entity to use Resource Message

e3a1af0

Bumped package version due to breaking changes

e87f399

ayushgnv force-pushed the simulation_world branch from 072d641 to e87f399 Compare July 1, 2025 04:38

		uint8 STATE_NO_WORLD = 4 # Simulation world is currently unloaded and a new world has not finished loading yet.
		# The simulation is inactive and cannot be started, stopped, or paused.

		@@ -0,0 +1,5 @@
		# This message is used to specify a resource, either by a URI or by its string content.

Proposal to add support for managing simulation worlds #4

Are you sure you want to change the base?

Proposal to add support for managing simulation worlds #4

Conversation

ayushgnv commented Apr 1, 2025

Proposal for World Management Services for Simulation Interfaces Standard

Uh oh!

pijaro commented Apr 8, 2025

Uh oh!

adamdbrw commented Apr 9, 2025

Uh oh!

ayushgnv commented Apr 11, 2025

Uh oh!

adamdbrw commented Apr 17, 2025

Uh oh!

adamdbrw commented Apr 24, 2025

Uh oh!

peci1 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mjcarroll commented May 12, 2025

Uh oh!

DLu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ayushgnv Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ayushgnv Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ayushgnv commented May 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DLu commented May 13, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ayushgnv Jun 27, 2025 •

edited

Loading

ayushgnv Jun 27, 2025 •

edited

Loading

ayushgnv commented May 13, 2025 •

edited

Loading