Modular Vehicle Systems: Working with Components (Advanced Users)

Vehicles are defined by Modular Vehicle Systems using Topology files. These topology files are simply assembly that contain several Components, which model the behaviour of the vehicle subsystems, such as engine, wheels, transmission, etc. Each component is a standard Vortex Studio Assembly file, and can be added, created, and edited using the Vortex Editor. So working with components is the same as working with any other Vortex assets, and this documentation assumes the user is already familiar with the Editor.

While there is no technical difference between components and assemblies, Modular Vehicle Systems was created according to certain conventions and practices, and it is strongly recommended that any new components or modifications should also follow those conventions. These conventions relate to interfaces, naming, logic implementation and modelling.

While this documentation attempts to provide information to work with Vehicle Systems effectively, the Vehicle Systems assets themselves provide the best illustration of how everything works. They are all accessible and editable, and can be used and copied and investigated to figure out how things work.

The main topics available for working with components are:

What's in a Component

While components can vary widely, most components have some standard objects, which are described below. As an example, refer to the Wheel component.

Object	Description
Interfaces	Each component contains several interfaces that control and parametrize the component. There are several interface names that will exist for most components: [Component] Interface: contains the fields that are used to tune and control the component. Most of these will likely be directly exposed at the topology level to the vehicle end user, though the topology assembly might include some additional common logic that interacts with this interface. [Component] Attachments: This interface contains the part pointers that are connected between the components to constrain them together. If this component contains a part, it should be output in this interface so that other component could connect to it. If this component contains a constraint that requires a part from another component, that should be exposed as a parameter in this interface. [Component] Transforms: If this component contains any parts that might be skinned to a graphics node, the part transform should be exposed in this interface. While it's technically possible to make a connection in the mechanism directly from the part in the component, this is a very poor practice. Instead, all transforms should be exposed in this interface, which is exposed at the topology level for the end user to connect to. Additional interfaces: If there are specific values that don't belong in the standard interfaces, additional VHL interfaces can be added. For example, the Wheel component contains a Wheel Contact interface that exposes the numerous outputs that describe the state of the wheel contact model for debugging purposes. These interfaces are the only fields that should be accessed by the user of the component, so if any value needs to be tuned or adjusted to parametrize or control the component, it must be exposed in one of these VHL interfaces.
Parts	If parts are needed to model various components, they are directly added to the component assembly. The mass properties of the part and dimensions of any collision geometries can be set to some default value, and a script (such as Mass Properties for many components or Wheel Properties for the Wheel) can be used to modify the properties based on user inputs.
Constraints	Any constraints that are needed to constrain the parts to other components can be directly added to the component assembly. Often the constraints will be missing one of the parts, since it is constraining to another component. For example, the wheel component has a Car Wheel constraint constraining it to the chassis, but the chassis is not present in this component. So one of the attachments in the constraint is exposed as a parameter in the Wheel Attachments interface, and the chassis part will be connected to this parameter in the topology file. Note that it is important to understand how to correctly use the 'Reference Object' field of the constraint attachments in order to have the constraints start from kinematically valid configurations. In many cases, the chassis part parameter is also connected to one of the Reference Object fields.
Scripts and Connections	Scripts can be used for several purposes in components. If the mass properties or collision geometry dimensions can be modified by the user, this likely has to be done using a script, since some of these properties can't be directly exposed in VHL, and the script can be used to make the interface simpler than the properties would otherwise appear. Most components contain a 'Controller' script that defines the functionality of the component, and controls the constraints that actually model the component. For example, an engine controller looks up the engine torque from a defined curve and sets the values in the engine constraint to produce the correct torque.
Additional Extensions	Currently only one other extension can exist in an assembly: the Wheel Adapter that is used to allow the wheel cylinder to use sophisticated tire models. This is also placed in the Wheel component and the interface is exposed similar to a controller or script.

Conventions

Components are simply assemblies, so it is not possible to rigorously enforce certain naming or logic or component conventions. Any user can change things as they prefer. But following certain conventions will make the modular vehicle systems much clearer over all. Below are some of the general concepts that have been followed for the existing templates.

All values that need to be tuned or controlled in the component must be exposed as VHL interfaces. The end user of a component (the template designer) should not be expected to dig into anything inside the component, except the list of interfaces at the top of the explorer tree. Tuning or connecting to any field in a script or constraint should not be necessary, and should be prohibited.
The three standard interfaces (Interface, Attachments, Transforms) should exist for most components (though some might not for certain components), and be placed at the top of the explorer tree.
The interface names for the components should refer to the type of component, not necessarily the exact component name. For example both the Clutch component and Torque Converter components are types of couplings, so the interface for both of these will be called "Coupling Tuning". While this is not strictly necessary, it makes it easier to replace components inside the templates, since the interface names will be common and connections and values will be kept after replacement.

Replace a Component

If a user is customizing a template, it is possible to replace a component with another one. For example, a user could convert a template from automatic to manual transmission. They could replace the torque converter with a clutch and the automatic transmission with a manual transmission (not created yet).

Replacing a component is done the same way as replacing any other assembly. Simply open the template, right click on the component assembly, and select Replace Assembly. You can then locate and choose any other component assembly. Once the replacement is finished, it is possible that some interface values and connections will be lost. Any interfaces and fields that are common between the old and new template will retain their connections or values, but any fields that no longer exist will show broken connections, and any new fields that didn't previously exist will have default values.

Modify a Component

The provided library of components does not cover all possible vehicle subsystem, so custom components might be needed. While the library of components will keep growing, there will always be some systems that aren't modeled yet, and certain specific behaviours that require custom logic.

The standard components provided with Vortex Studio should not be modified. Since they are 'owned' by the Vortex installation, they could be updated or replaced when the software is upgraded, and any modifications would be lost. Therefore modifying a component actually means making a copy of an existing component, and modifying the copy. This can be done either in a file explorer by simply copying and renaming the .vxassembly in a new folder, or using the Save As function inside the Editor.

In order to actually use the new component, the user would have to use a custom template, since standard templates only refer to standard components. A custom template can be created as outlined in Working with Templates.

Modifying a component is done the same way as any other assembly in Vortex. The component assembly contains parts, constraints and logic, so modifying the component simply means editing the objects in the component.

One of the most common modifications could be to simply edit the control script that contains the model of the vehicle subsystem. For example, the user might want to implement a more sophisticated engine model than the one provided by the Engine component. But since the new engine model still requires the same drive shaft part and hinge constraint, there is no need to modify any of the actual dynamic objects in the component. However, even though only the script needs to be modified, the only way to modify the script is to make a copy of the entire component (assembly, part and script) and modify the script in the copy.

Create a New Component

While it is possible to create a component from scratch by creating an assembly and adding all the necessary pieces, it is not recommended. It is likely easier to start from an existing component and delete unneeded parts, constraints and logic, and use that as a base for a new component.