Modular Vehicle Systems: Working with Topology Files (Advanced Users)
Vehicles are defined by Modular Vehicle Systems using Topology files. Each topology file is a standard Vortex® Studio Assembly file, and can be added, created, and edited using the Vortex® Studio Editor. So, working with topologies is identical to working with any other Vortex asset in the editor, and this documentation assumes the user is already familiar with the basic workflows.
While there is no technical difference between topologies and assemblies, Modular Vehicle Systems was created according to certain conventions and practices, and it is strongly recommended that any new topology or modifications of existing topologies should also follow those conventions. The conventions relate to interfaces, naming, logic implementation and connection of components.
While this documentation attempts to provide information to work with Modular Vehicle Systems effectively, the Modular Vehicle Systems assets themselves, available in the Vortex® Studio Samples package, 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.
After installation, the default path of the Vortex Studio Sample package is C:\CM Labs\Vortex Studio Content <VERSION>\Samples.
The main topics available for working with topologies are:
What's in a Topology file
While topologies can vary from very specific vehicles with no options, to highly parametrizable models with sophisticated logic, most topologies have some standard objects, which are described below. As an example topology that contains these objects, refer to the front-wheel drive topology file (FWD).
| Object | Description |
|---|---|
| Interfaces | Each topology contains several interfaces that control and parametrize the vehicle itself. These are described in more detail in Modular Vehicle Systems. These interfaces are the only fields that should be accessed by the user of the topology, so if any value needs to be tuned or adjusted to parametrize or control the topology, it must be exposed in one of these VHL interfaces. |
| Components Folder | The components folder contains the components and various logic and connections, as described below. |
| Components | These are sub-assemblies that contain the vehicle components. |
| Vehicle Topology | This connection container contains all the connections that physically link the components together. While it looks like a topology graph, the actual data carried by the connections is a part pointer, which is given to the constraint in the connected component in order to complete the constraint. For example, the engine component has a Shaft output, which contains a pointer to the part that represents the engine drive shaft. The torque converter component contains a part that represent the output shaft of the torque converter, and a Gear Ratio constraint that represents the actual fluid coupling behaviour of the torque converter. This constraint must be between the engine drive shaft and the torque converter output shaft, so a pointer to the engine drive shaft is passed from the engine component to the torque converter component using the topology connection. |
| Component Positioner | This script contains the logic that defines the positions of all the components, based on a set of parameter fields. For example, the script in the FWD topology file takes four numbers (front position, rear position, width and height) and calculates the complete transforms for all of four tires. It also uses a single position and distance to distribute all of the drive train components in a line so they visualized with the constraint or position debug view. This functionality is not strictly necessary, since the transforms of the components could be either hard-coded or exposed directly. But this parametric calculation provides a much simpler interface for the end-user of the topology. The script uses the paused_update callback so that the positions will be updated live, even while entering the numbers in editing mode. |
| Component Positions | This connection container simple connects the outputs calculated by the Component Positioner to the Local Transform of each component. |
| Collision Rules | This can contain a collision rule to disable collision between the components at the topology level. This might not be needed, but it is possible that the collision geometries of the various components could collide accidentally. |
| Controls Folder | This folder contains various logic that controls the vehicle, that interacts with multiple components and hence can not be placed inside the related component. For example, the Steering Controller in the FWD topology file calculates the Ackermann angles for the two front wheels. |
Conventions
Topologies 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 topologies.
- All values that need to be tuned or controlled in the topology must be exposed as VHL interfaces. The end user of a topology file should not be expected to dig into anything inside the topology, except the list of interfaces at the top of the explorer tree. Tuning or connecting to any field in a script or component should not be necessary, and should be prohibited.
- There are three standard interfaces defined that will exist for almost all topologies: Vehicle Control, Component Configuration and Part Transforms, as documented in Modular Vehicle Systems Documentation. These should be the first three interfaces in every topology file.
- After the three standard interfaces, there should be an interface for every component. These interfaces are named after the component, followed by the suffix 'Tuning'. In most cases, this could be an exact reflection of the interface that is provided by the component itself, which makes creation of this interface easy, as you can simply drag all the inputs and outputs into the Interface Editor. However, in certain cases it might be clearer to combine several related components into one common interface. For example, the FWD topology file (and all provided vehicle topologies) combine wheel properties for each axle into a single interface, where Front Wheel Tuning provides the tuning for both the front-right and front-left wheels, since they will always be the same.
- 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 or topologies, since the interface names will be common and connections and values will be kept after replacement.
Replace a Topology
If a vehicle mechanism was created with one topology, the user can change this topology for another. For example, a vehicle created with a RWD topology could be replaced with the AWD topology if the user discovers that the vehicle has four-wheel drive.
Replacing a topology is done the same way as replacing any other assembly. Simply open the vehicle mechanism, right click on the topology assembly, and select Replace Assembly. You can then locate and choose any other topology file. 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 topology assembly 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 Topology
The provided library of topology files does not cover all possible vehicle configurations, so custom topologies might be needed. It might be that the required vehicle has a manual transmission, but all of the available topology assembly have an automatic. Or perhaps more wheels could be added to an existing topology assembly.
The standard topology files 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 topology file actually means making a copy of an existing topology file, 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 topology file, the vehicle mechanism would either be created by adding the new topology, or an existing mechanism could be modified by replacing the existing topology with the new one, as outlined in the Replace a Topology section.
Modifying a topology file is done the same way as any other assembly in Vortex. The topology assembly contains component sub-assemblies, so replacing a component could be done by right-clicking on it and selecting Replace Assembly, then navigating to the location of the new component. Components can simply be deleted, added, copied, pasted or duplicated as needed.
An effort has been made to standardize the names of fields between the variants of a type of component, so many times the connections and field values will be kept if a component is simply replaced. For example, if a torque converter is replaced with a clutch, the shaft connection from the engine will still be kept. Some of the fields have the same names and meanings, such as the Shaft Speed and Shaft Power outputs. But the parametrization and control of the new clutch has little in common with a torque converter, so the set of input fields will be different between the components.
So while some values and connections will be retained if components are replaced, there are several pieces of the topology that will have to be updated after adding and removing components..
- The interfaces referencing the old components should be removed, and new interfaces and fields will probably have to be added for the new components.
- The topology will probably have to be updated to remove connections to the deleted components, and create connections to the new ones.
- The logic and connections of the Component Positioner will have to be updated.
- Controls might have to be updated or added to control the new components.
Create a New Topology File
While it is possible to create a topology 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 topology and delete unneeded components and logic, and use that as a base for a new one.