When Should I Change the Content of a Simulation

As described in this page, the Vortex application has three application modes. Ideally all content should be created, loaded, removed and modified while the application is in the Editing mode.
In Editing mode, you are guaranteed that any changes you make to the objects in the simulation will be taken into account when you start it.

Applications like the Vortex Studio Editor and Vortex Studio Player follow this recommendation. Allowing the user to load/unload and modify content before the play button is pressed.
In the Editor, the toolbox will be greyed out when the simulation start and in the Player the Browser tab will disable itself.

While this is the recommended way of changing content in a Vortex application, the Vortex API does not prevent the developer from doing it while the simulation is running.
So while it will work, there are some caveats and possible impacts on your simulation.

What Happens If I Load/Unload/Modify Content During the Simulation?

As often with technology, the correct answer is: it depends.

Most dynamics extension were developed with support for being added/removed to/from a running simulation.
What that means is that when in Editing mode these extensions will wait for the simulation to start (switch to Simulating mode) before doing their initialization.
But if they are added directly to a running simulation, they will do their initialization right away; they won't wait for the application mode change.
Some older dynamics features might present some hiccups if they do not support this completely. But most newer extensions should adapt just fine.

So while it might look like most everything will work fine, there are still some important impacts and restrictions to know about when adding content in a running simulation.

Performance

Loading content files on a simulator has an impact on performance relative to the size of the content files that are loaded.
Vortex does not support asynchronous loading. So basically loading content while the simulation is running will halt the simulation while the content is being loaded.

In a distributed simulation, this must be performed on every node and the simulation will only resume when all nodes have confirmed to the master that the content is correctly loaded.
This is why loading content is mostly done in Editing mode before the simulation starts running. Editing mode is good time to show a loading screen and perform whatever costly operations you need before the user starts the actual simulation.

Callbacks

Modules or extensions implementing the IApplicationListener interface upon being added to the simulation won't receive an initial onApplicationModeChange() callback.
This is even if the Vortex application was initially started in Editing mode and than switched to Simulating before adding the new content.

On the other hand, extensions will receive an initial call to onActive() when they are added to the simulation even if already in Simulating mode. Similarly, they will receive the onInactive() callback while being removed from the simulation, even while it is running.

Parameters

Parameter fields on extensions are great for allowing to customize the behaviour of an extension. However, they should not be used as a replacement for an Input.
Extensions that come with Vortex will not check the value of parameters after being added to the simulation.

Configurations

Configurations are a very convenient way to applying a predefined set of modification to some content. Configurations are set when the application is in Editing mode before the simulation is run and they cannot be changed in Simulation mode.
Also, activation of a configuration can only happen in Editing mode. If you try to activate a configuration in any other mode you will receive an error about using an invalid application mode.

Python 3 Scripts

The DynamicsScript extension refers to an external Python 3 script file on disk.  In Editing mode, this file is constantly monitored for any change and the internal code object is automatically updated. This is not the case in Simulating, so any change on the source file will not take effect
until the next start of the simulation.

However, a DynamicsScript extension added to the simulation in Simulating mode will get its code read and executed.

Cables

Cables can be added to the simulation while it is running but it is important to keep in mind that cables usually require some frames of simulation before they get to their rest state.
Instead of adding new cables during the simulation, it is recommended to add them in Editing mode and use their Active input to enable or disable them during the simulation.

Key Frames

Restoring a key frame that was taken prior to adding new content will generate an error. Vortex will attempt to restore whichever extensions were in the key frame as well as restore the simulation time but of course the new objects won't be changed.
In other words, it is not recommended to restore key frames that only had partial content.

Deformable Terrain, Earthwork Zone & Vegetation Field

Loading content that contains a deformable terrain, a earthwork zone or a vegetation field while simulation is not in itself an issue and should function as if it was loaded while in Editing Mode.

What will not work is if you attempt to create those extensions and their dependencies dynamically while the simulation is running (e.g. for some kind of terrain streaming).
The underlying extensions need to compute data in Editing mode and thus cannot work properly if created while the simulation is already running.

External Engines

Lastly, if you are using an external graphic engine integration like Unreal or Unity we cannot give any guarantee on how the external engine will react when content is added/removed while the simulation/game is running

What Happens If I Create New Content During the Simulation?

While creating content dynamically can be powerful, it is also a tricky act to balance.

When content is loaded from file, the VxSimulationFileManager takes care of notifying all nodes in the networked simulator of the content that needs to be loaded.
However, there is no such facility for content that is created dynamically and this is true whichever application mode the application currently is in.

In some cases it does not matter, a Python dynamics script running on the master node could create dynamics object with no graphical representation and that would work fine.
But in all cases, the responsibility of what needs to be loaded on which node to work properly falls on the developer.

Also, keep in mind that creating a large number of object dynamically could incur performances costs, similarly than if they were loaded from files.

I'd Like to Safely Disable Some Content During Simulation

Sometimes it can be useful to disable some content extensions in the simulation without actually removing them completely. It avoids the cost of unloading the object and allow to re-enable it without paying that cost again.

Here's a recipe that allows you to do that.

1. Set the object's parts Control input field to Static.
2. Move the object out of the way. For example, this might be underground.
3. Deactivate the collision detection for all collision geometries of the object. All collision geometries have a Enabled field in their Collision detection container. Just set it to false.
4. Deactivate the object's graphics. This implies, going through all nodes of the graphics gallery and for each node setting the Visible input to false.