VSE Extensions#

VSE system provides multiple options to extend its functionality. VSE allows adding tools to simplify work and new scenario elements to the VSE.

Custom Scenario Editor Extension top#

The scenario manager finds all classes implementing the IScenarioEditorExtension in the loaded Assembly and creates an instance of each implementation. If the implementing class extends the MonoBehaviour, the manager adds a new game object with the class component to the VSE. Otherwise, the manager uses a default constructor to create an extension instance. A custom extension instance will be created and initialized asynchronously by a scenario manager. Built-in extensions (like InputManager) initialize before the custom extensions. The order of custom extensions cannot be set what may lead to race conditions if custom extensions' initialization methods require each other.

Custom scenario editor extension allows to add a separate class for managing logic, for example, VSE uses ScenarioAgentsManager and ScenarioControllablesManager that manage different scenario elements during their lifetime. Extensions' initializations occur before the VSE starts, it can load and cache required resources.

Serialized Extension top#

VSE scenarios are serialized and deserialized by all the scenario editor extensions that implement ISerializedExtension. Each serialized extension gains access to the scenario data sequentially and shares the same scenario data object. Serialization and deserialization methods return the true result if the operation succeeds, and false otherwise so VSE cancels the operation. A serialized extension may edit the existing data. But as the order of custom extensions is not fixed, it may lead to a race condition.

Warning: currently, VSE Runner does not support passing custom scenario data to the Simulator, so the saved data may be used only inside the VSE (for example, VSE camera orientation).

Custom Scenario Element Source top#

Default VSE scenario element sources are ego agents source, NPC agents source, pedestrian agents source, and controllables source. Inspector Add Panel instantiates an UI section for each ScenarioElementSource game object found inside the Scenario Manager. If a custom source is needed, the best way is to instantiate a ScenarioElementSource implementation during a Custom Scenario Editor Extension's initialization and parent source's transform to extension (if it overrides MonoBehaviour) or Scenario Manager. Add panel will prepare buttons for each source variant, and it will call the OnVariantSelected method on the left mouse button down. By default, it instantiated a new element and drags it.

Built-in Extensions top#

VSE provides some additional features that in the future may be available as an external plugin. Right now, they are built-in and available out of the box in the VSE.

Scenario Nav Origin top#

Scenario Nav Origin is a separate scenario element with custom properties. Only one Scenario Nav Origin may be available in the scenario. If a loaded map contains a Nav Origin, the extension will create a Scenario Nav Origin using the map's Nav Origin data. A Scenario Nav Origin created from the map data cannot be removed from the scenario. Those behaviors require a custom source implementation.

There is a nav elements section in the add panel to handle the dedicated behavior. A Custom Scenario Element Source allows dragging a new Scenario Nav Origin if there are no objects of this type in the scenario. If there is an existing Scenario Nav Origin, instead of adding a new instance, VSE selects the existing one and centers the camera on it. Nav extension is a Serialized Extension implementation and adds the Nav Origin data to the serialized scenario.

A Scenario Nav Origin can be moved around the map like other scenario elements and has a dedicated parameter edit panel after selection.