Modular Vehicle Systems allows to create vehicles in Vortex® Studio in a modular way. It provides a library of components that are common to most of the vehicles such as wheel, motor, transmission, torque converter and others.

All components are parametrized with interfaces to set, and get important values from the component. It also provides a set of predefined vehicle topologies that are common to the industry, provided as content files in the Vortex® Studio Samples package. A topology file is simply an Assembly file that contains a set of components that are attached/connected in such a way that they are ready to model a particular class of vehicles.

For example, the topology called FWD can be used to model any vehicle with four wheels, that has an engine, an automatic transmission, a torque converter, and a differential. The only difference between vehicles of a given class is the particular set of values given to the components it contains (masses, dimensions, gear ratio, torque table etc.). Starting the creation of a new vehicle from a topology is the right way to use the Modular Vehicle Systems.

One of the key points of the Modular Vehicle Systems is the fact that all elements (components and topology) are made up of standard Vortex® Studio objects: Assemblies and Parts but also Connection and Python3 etc).

This opens the possibility to easily create other topologies to model classes of vehicles that are not already covered by the existing set. Also, new components can be created to provide functionalities that do not exist in the existing library of components. Finally as the behaviour of each component is implemented via Python scripts, any specific behaviour of any component can be fine tuned or completely redefined to fulfill particular engineering requirements.

Vortex Studio also provides a set of completed vehicles as example, readily available in the Vortex® Studio Samples package.

For a step by step procedure of how to create a modular vehicle, please refer to the Tutorial: Creating a Vehicle with Modular Vehicle Systems.

After installation, the default path of the Vortex® Studio Samples package is C:\CM Labs\Vortex Studio Content <VERSION>\Samples.

Using Modular Vehicle Systems

Users can take advantage of Modular Vehicle Systems by adding a topology assembly to their mechanism.

Topology assembly files define which components exist in different classes of vehicles, how they are connected, and some additional logic common to the vehicle. However, the actual properties and tuning of the vehicle (dimensions, mass properties, torques and gear ratios) are defined by the user using the interfaces of each of the components. This allows to quickly tune different vehicles that belong to a given class. For example, the RWD topology file can be used to model a sedan, a pick-up truck, or a single-axle dump truck, simply by changing the values in the topology's interface.

It should be noted that topology files do not include graphical assets, since these are specific to a particular vehicle. Therefore, the content creator must use their own Graphics Gallery for applications that require graphics, and link it with the parts that form the vehicle, e.g., the chassis or the wheels.

How to Create a New Vehicle

The first step to do when creating a new vehicle is to look at the given set of topology file under the sample directory. Find the one that has the closest drive train compare to the actual vehicle that has to be modelled. If there is one that matches exactly, go to the Step by Step tutorial where a detail step by step procedure is given. If there is no topology file that matches exactly the vehicle to be modelled, a new topology file needs to be created. In this case, refer to the advance document: Working with Topology Files.
Finally, the set of pre-defined components is quite extensive but if there is a need to create a new component, please refer to the following page: Working with Components.

It is worth mentioning that when a component file is loaded in the Vortex® Studio Editor some warning messages may appear. This is normal because components need to be connected with each other and this connection is only established at the topology level, that is, a level above the components. For example, when loading a Differential component, its input shaft is not set. Setting the input shaft will only be done when the Differential component will be used by a topology file with proper connections. Likewise, topology files may show warning messages, for example if tuning tables are not set, e.g., like the engine torque table. This will be resolved when adding the topology to the final vehicle mechanism file where the actual engine characteristics are known and can be provided via the topology interface.

Topology File

Topology generally contains three categories of interfaces:

Common Interfaces that exist for all:
- Vehicle Control: Contains basic inputs to control the vehicle (e.g., throttle and steering), and outputs to report the current state (e.g., speed, engine RPM).
- Component Configuration: Parameters to set the relative positions of all components, some properties that are common to all components, and a field to specify a user body to attach to the vehicle chassis.
- Part Transforms: Transforms of all parts in the vehicle system, which can be connected to user graphical nodes.
Component Interfaces that exposes the parametrization and tuning values for each component.
Custom Interfaces that control any custom logic defined. For example, for a front-wheel steered vehicle, a script called steering controller implements the Ackermann steering system and the tuning of that logic is exposed in an interface, Steering Tuning, at the topology level.

An example of a complete vehicle based on 3758345837 can be seen from the Vortex Studio Samples in the Car - Hatchback mechanism file.

The mechanism contains the following objects (visible in the mechanism's Explorer panel):

Vehicle Interface: This is the interface defined inside the mechanism, which is how the user of this mechanism will control and interact with the mechanism.
Graphics/Hatchback: This is the Graphics Gallery of the vehicle.
Graphics/Skin: This connection container contains connections linking the vehicle's Part Transform outputs to the corresponding nodes of the Graphics Gallery.
Physics/Assembly: This assembly contains the part representing the body of the car. This is where the collision geometry and mass properties of the car body are defined.
Physics/FWD: The front-wheel drive (FWD) topology on which this vehicle is based. It contains the three types of interfaces contained in all topology assembly as seen above. These interfaces are how the specific vehicle tuning and parametrization is specified.
Physics/Collision Rules: Contains a collision rule that disables collisions between the vehicle FWD and Assembly. This prevents the wheels from colliding with the body of the vehicle.
Controls: This folder contains various scripts and connections to control the vehicle and provide the signals that are defined in the Vehicle Interface.

Topology Library

A set of topology is available in C:\CM Labs\Vortex Studio Content <VERSION>\Samples. For each of them, a succinct description is given below and a more detailed description for the 3758345837.

AWD - All Wheel Drive Vehicle

This topology files can be used to model any vehicle that belongs to the class of vehicle where 4 wheels are driven. Such vehicles is made of the following components: a 3758345837, an 3758345837, a 3758345837, an 3758345837, one 3758345837, two 3758345837 and four 3758345837.

AWD Double Wishbone

This topology file is similar to the 3758345837except that it uses the Double Wishbone component at each of the wheels.

RWD - Rear Wheel Drive Vehicle

This topology file is met to be used for any vehicle that belongs to the class of vehicle that has four wheel where rear wheels are driven. Such vehicles are made of the following components: a 3758345837, an 3758345837, a 3758345837, an 3758345837, one 3758345837and four 3758345837.

Tandem - Truck

This topology file is met to be used with vehicles that have two driven rear axles. Such topology uses the following components: a 3758345837, an 3758345837, a 3758345837, an 3758345837 a transfer case, two 3758345837and 6 3758345837. Notice that the front axles is also driven. Such topology is in general met for heavy vehicle therefore it includes a retarder component.

Tracked Vehicle - 2x2

This topology file is met to model vehicles with track system. In this case, there is two tracks with two wheels each, one idler and one sprocket, and so the 2x2 in the name. The track system is of type rigid meaning that there is nos suspension and the track that touches the ground is rigid so that it doesn't deform. Such topology file includes the following components: a 3758345837, an 3758345837, an 3758345837, two 3758345837, four 3758345837 and two 3758345837.

Trailer - 2 Axle

This topology file is met to model trailers with two axles. It simply includes a 3758345837and four 3758345837.

FWD - Front-Wheel Drive Vehicle

Here is a more detail description of a topology file.

The FWD topology contains a 3758345837 component with four 3758345837 components (two steered and driven wheels in front, two wheels in the rear) and a drive train consisting of an 3758345837, 3758345837, 3758345837 and one 3758345837.

The topology of the components is shown below. All of the components are directly constrained to the chassis, and the power train is connected in series providing power from the engine to the wheels.

FWD Common Interfaces

The FWD vehicle contains the common interfaces below.

Interface Category	Name	IOP	Type	Description
Vehicle Control	Engine Running	Input	bool	Set the engine to be running.
Vehicle Control	Throttle	Input	double	Throttle input between 0 and 1.
Vehicle Control	Brake	Input	double	Brake input signal from 0 to 1.
Vehicle Control	Steering	Input	double	Steering input signal from 0 to 1.
Vehicle Control	Gear	Input	int	Selected gear, positive for forward, negative for reverse, zero for neutral.
Vehicle Control	Speed	Output	double	Current forward speed of the vehicle.
Vehicle Control	Engine RPM	Output	double	Current engine RPM.
Vehicle Control	Current Gear	Output	int	Index of the current gear, negative for reverse, 0 for neutral, positive for forward.
Component Configuration	Drivetrain Position	Parameter	vector3	Position relative to the Chassis to place the first drivetrain component.
Component Configuration	Drivetrain Spacing	Parameter	double	Each successive drivetrain component is placed this distance in front of the previous.
Component Configuration	Wheel Position Front	Parameter	double	Position of front axle.
Component Configuration	Wheel Position Rear	Parameter	double	Position of rear axle.
Component Configuration	Wheel Spacing	Parameter	double	Distance between left and right wheels.
Component Configuration	Wheel Height	Parameter	double	Vertical position of wheels.
Component Configuration	Shaft Mass	Parameter	double	Mass of internal shafts in kg.
Component Configuration	Shaft Inertia	Parameter	double	Moment of inertia of internal shafts, assumed spherical (in kg m²).
Component Configuration	Body Attachment Point	Parameter	AP*	Attachment point on the body to be attached to the chassis part.
Part Transforms	Chassis Transform	Output	Transform	Current transform of chassis part.
Part Transforms	Wheel FL Transform	Output	Transform	Current transform of front left wheel part.
Part Transforms	Wheel FR Transform	Output	Transform	Current transform of front right wheel part.
Part Transforms	Wheel RL Transform	Output	Transform	Current transform of rear left wheel part.
Part Transforms	Wheel RR Transform	Output	Transform	Current transform of rear right wheel part.

FWD Component Interfaces

The vehicle contains several components, and each of their interfaces appears at the topology level also.

Interface	Component
Chassis Tuning	3758345837
Engine Tuning	3758345837
Coupling Tuning	3758345837
Transmission Tuning	3758345837
Differential Tuning	3758345837
Wheel Front Tuning	Left and Right Front 3758345837
Wheel Rear Tuning	Left and Right Rear 3758345837

FWD Custom Interfaces

The vehicle also contains interfaces for logic customized to this particular topology file.

Interface	Name	IOP	Type	Description
Braking Tuning	Max Torque	Input	double	Maximum brake torque per wheel.
Braking Tuning	Front Rear Bias	Input	double	Bias between torque on front and rear wheels. 0.5 for equal torque on front and rear, closer to 1 means higher torque on front wheels, closer to 0 means higher torque on rear wheels.
Steering Tuning	Max Steering Angle	Input	double	Maximum steering angle of the inside wheel in degrees.

Component Library

Vehicle Systems models are based on a library of components. Each component can contain dynamic objects (parts, constraints, collision geometries), logic (scripts and connections) and an interface with fields to tune and parametrize the component.

Chassis

The Chassis component represents the main chassis or frame of a vehicle. It is modelled simply as a single part. If the user has a part defined to represent the body of the vehicle (in order to create collision geometries or add additional parts and constraints), the Component Configuration common interface contains a field where the user part can be selected to be attached to the chassis part.

There is no logic or control in the chassis, and the interface only contains fields to define the mass properties of the chassis part.

Chassis Interface

Name	IOP	Type	Description
Mass	Input	double	Mass of chassis
Centre of Mass	Input	Vector3	Vector of centre of mass offset
Inertia	Input	Vector3	Components of diagonal inertia matrix

Chassis Attachment

Name	IOP	Type	Description
Chassis Part	Input	Part*	The chassis part
Body Attachment Point	Parameter	Attachment Point	Attachment point on the body to be attached to the chassis part

Engine

The Engine component is used to model the behavior of an internal combustion engine by applying a torque to a shaft part using a hinge constraint.

Engine component

The torque applied by the engine is determined by the torque table, which specifies the maximum torque of the engine for the range of drive shaft RPM. The table is defined for wide open throttle, and the actual torque applied will be decreased for lower throttle positions. The engine will also apply braking torque if the actual speed of the shaft is higher than what is expected for the current throttle position.

The engine incorporates the behavior of idle speed controller. It will attempt to maintain the specified Idle RPM, applying up to the maximum torque defined in the torque table at that RPM.

The engine also contains several fields that allow tuning and modification of the engine behavior, such as adding or subtracting additional torque or shaft friction at run time.

Engine Interface

Name	IOP	Type	Description
Engine Running	Input	bool	Set the engine to be running. When False, engine drive torque will be zero.
Throttle	Input	double	Input throttle between 0 and 1
Throttle Delay	Input	double	Set the maximum rate the throttle can be increased, simulating the effect of engine response lag. Throttle rate of change will be limited so it can go from 0 to 1 in the specified time.
Torque Scale	Input	double	Scaling factor that is multiplied by the current torque from the torque table.
Torque Added	Input	double	Torque added to the computed engine torque.
Braking Torque Scale	Input	double	Scaling factor that is multiplied by the current torque from the braking torque table.
Braking Torque Added	Input	double	Torque added to the computed engine braking torque.
Shaft Friction	Input	double	Friction torque applied to the shaft.
Shaft Mass	Input	double	Mass of drive shaft in kg.
Shaft Inertia	Input	double	Moment of inertia of drive shaft, assumed spherical (in kg m²).
Torque Table	Parameter	file	Engine torque table CSV file with full throttle torque specified at each RPM.
Idle RPM	Parameter	double	Idle RPM.
Max Torque	Output	double	Maximum engine torque that can be delivered by the engine, calculated from the engine torque table.
Max RPM	Output	double	Maximum engine RPM, calculated from the engine torque table.
Max Power	Output	double	Maximum engine power (in watts, W) that can be delivered by the engine, calculated from the engine torque table.
Max HP	Output	double	Maximum engine power (in horsepower, hp) that can be delivered by the engine, calculated from the engine torque table.
RPM at Max Power	Output	double	Engine RPM at maximum power, calculated from the engine torque table.
RPM at Max Torque	Output	double	Engine RPM at maximum torque, calculated from the engine torque table.
Engine RPM	Output	double	Current engine RPM.
Engine HP	Output	double	Current power applied by engine in hp.
Shaft Speed	Output	double	Speed of output shaft in rad/s.
Shaft Torque	Output	double	Net torque on output shaft (in newton-meters, N m).
Shaft Power	Output	double	Net power on output shaft (in watts, W).

Engine Attachments

Name	IOP	Type	Description
Shaft Part	Input	Part*	Shaft part exposed from this component
Chassis Part	Parameter	Part*	Chassis part where the motor shaft is attached

Torque Converter

The Torque Converter component models a hydrodynamic fluid coupling. It contains a shaft rotating with a hinge constraint, and the coupling force is applied using a gear ratio constraint.

Torque Converter component

The torque converter controls the coupling torque between the input and output shafts using a simple model. Coupling torque is related to the square of the input shaft speed (though torque decreases as the shaft speeds approach the same speed). The torque is calculated to correctly match the stall point; that is, when the output shaft is fixed and the input shaft is spinning at the Stall RPM, the coupling torque will equal the Stall Torque.

The torque converter will also provide torque multiplication, where the torque on output shaft will be higher than the input torque, with a factor equal to the Torque Multiplication input field when the output shaft is stopped, and will decrease to no multiplication when the input and output shafts approach the same speed.

The torque converter also provides a Slip field that can be tuned to allow more slip when the input and output shafts are nearly the same speed. More slip generally results in more stable simulation of the torque converter.

The torque converter also contains the coupling torque to be directly modified at run time by adding or subtracting additional torque.

Coupling Interface

Name	IOP	Type	Description
Coupling Torque Scale	Input	double	Coupling torque is calculated from the model of the torque converter, then multiplied by Coupling Torque Scale. Coupling torque is the maximum torque between the torque convert input and output shafts.
Coupling Torque Added	Input	double	Torque that is directly added to the coupling torque. This can be used to simulate a locking mechanism. A negative torque can be used to reduce the overall coupling.
Stall RPM	Input	double	The RPM that should be reached when full throttle and full brakes are applied. This is used to tune the coupling torque function of the torque converter. Unless otherwise known, this could be set to the RPM and Max Torque value from the engine.
Stall Torque	Input	double	The torque that the engine will apply at stall RPM. This is used to tune the coupling torque function of the torque converter. Unless otherwise known, this could be set to the Max Torque value from the engine.
Torque Multiplication	Input	double	Torque multiplication factor at 0 speed ratio.
Input Shaft Speed	Input	double	Speed of input shaft, from previous component.
Slippage	Input	double	Amount of slip to allow when speed ratio is near 1. Setting this lower will result in less slip at high speed, but can cause instability.
Speed Ratio	Output	double	The current speed ratio (CSR), the output shaft speed divided by input shaft speed.
Coupling Torque	Output	double	Torque applied to couple the input and output shafts.
Shaft Speed	Output	double	Speed of output shaft (in rad/s).
Shaft Torque	Output	double	Net torque on output shaft (in newton-meters, N m) including torque multiplication.
Shaft Power	Output	double	Net power on output shaft (in watts, W) including torque multiplication.
Shaft Mass	Parameter	double	Mass of output shaft in kg
Shaft Inertia	Parameter	double	Moment of inertia of output shaft, assumed spherical in kg m²

Automatic Transmission

The Automatic Transmission component models a transmission that shifts automatically based on input shaft RPM. It contains a shaft rotating with a hinge constraint, and the ratio of the gear between the input and output shafts is modelled using a gear ratio constraint.

Automatic Transmission component

The Automatic Transmission has a defined gear ratio table, and will shift gears automatically based on the input shaft RPM and throttle position. If the throttle position is below the Low Shift Throttle, the transmission will shift up or down based on the Low Shift Up and Low Shift Down inputs. If it is above the High Shift Throttle, the transmission will shift up or down based on the High Shift Up and High Shift Down inputs. If the throttle is in between this range, the shift points will be linearly interpolated.

Shifting gears will cause the ratio of the transmission constraint to change gradually over the Transition Time. After a shift, a subsequent shift will be prevented for the time defined by the Shift Again Delay.

Additional tuning inputs are provided to scale all the shift points, set efficiency of the transmission and directly apply friction.

Transmission Interface

Name	IOP	Type	Description
Gear Selection	Input	int	Selected gear, positive for forward, negative for reverse, zero for neutral.
Min Gear Selection	Input	int	If a transmission should be prevented from shifting into the lowest gears, this parameter can be set to the number of the lowest allowable gear. Set 0 for full range, negative for reverse.
Park	Input	bool	True to enable parking mode, locking transmission shaft.
Transition Time	Input	double	Transition time (in seconds) during shift between previous gear and next gear. During this time, gear ratio will linearly change from previous to next gear ratio.
Shift Again Delay	Input	double	After a gear change has occurred, automatic shifting will be prevented until this amount of time has passed (in seconds).
Low Shift Throttle	Input	double	When current Throttle is at or below this value, Low Shifting values will be used. Between Low and High Shift Throttle, value will be linearly interpolated.
High Shift Throttle	Input	double	When current Throttle is at or above this value, Low Shifting values will be used. Between Low and High Shift Throttle, value will be linearly interpolated.
Low Shift Down	Input	double	Point to shift down at low shifting throttle position. Shift will happen when input shaft RPM < Shift Down * Shift Scale.
Low Shift Up	Input	double	Point to shift up at low shifting throttle position. Shift will happen when input shaft RPM > Shift Up * Shift Scale.
High Shift Down	Input	double	Point to shift down at high shifting throttle position. Shift will happen when input shaft RPM < Shift Down * Shift Scale.
High Shift Up	Input	double	Point to shift up at high shifting throttle position. Shift will happen when input shaft RPM > Shift Up * Shift Scale.
Shift Scale	Input	double	Scale that multiplies the shift points. If this is 1, Shift Down and Shift Up correspond to RPM of input shaft. Alternatively, this can be set to the max RPM of the engine, which means the Shift points can be set as ratios of max RPM.
Shaft Friction	Input	double	Directly adds friction on the output shaft of the transmission (in newton-meters, N m).
Efficiency	Input	double	Efficiency of coupling. Friction is applied to output shaft proportional to the power transmitted through the transmission.
Shift Efficiency	Input	double	Efficiency is often lower while shifting gears, so during Transition Time, Shift Efficiency determines friction on output shaft.
Input Shaft Speed	Input	double	RPM of shaft feeding into transmission.
Throttle	Input	double	Current throttle position.
Gear Ratio Table	Parameter	file	CSV file containing gear ratios of the transmission. Starting with negative values for reverse gears, then zero for neutral, and positive values for forward gears.
Shaft Mass	Parameter	double	Mass of output shaft (in kg)
Shaft Inertia	Parameter	double	Moment of inertia of output shaft, assumed spherical (in kg.m²)
Current Gear	Output	int	Index number of current gear, negative for reverse, 0 for neutral, positive for forward.
Gear Ratio	Output	double	Ratio of current gear.
Shift Transition	Output	bool	True during shift transition.
Shift Up RPM	Output	double	Shift Up RPM based on current throttle position.
Shift Down RPM	Output	double	Shift Down RPM based on current throttle position.
Shaft Speed	Output	double	Speed of output shaft (in rad/s).
Shaft Torque	Output	double	Net torque on output shaft (in newton-meters, N.m).
Shaft Power	Output	double	Net power on output shaft (in watts, W).

Differential

The Differential component models a differential that splits the input torque between two output shafts. It contains two shafts, each rotating with a hinge constraint. The speeds of all of the shafts is related by a differential constraint.

The differential component can be used to model a standard differential between two wheels, but can also be used to represent a transfer case that splits torque between multiple driven axles.

The Gear Ratio determines the ratio of the differential, where a higher ratio results in higher torque and lower speed in the output shafts. By default the torque on the output shafts is equal, but the Torque Bias can used to set the bias towards one of the output shafts.

The speeds of the output shafts can be constrained by specifying a Lock Torque. The ratio of the speeds can be set by defining the Lock Ratio, which can be used to drive a skid-steer system.

Differential Interface

Name	IOP	Type	Description
Enable Differential	Input	bool	True to enable differential connection between shafts. When False, differential will be disabled, but lock can still be active.
Gear Ratio	Input	double	The gear ratio of the differential: ratio of input shaft speed to average output shaft speed.
Torque Bias	Input	double	The torque bias between shaft 1 and shaft 2. 0.5 means even torque split, closer to 1 means higher torque on shaft 1, closer to 0 means higher torque on shaft 2.
Lock Torque	Input	double	Torque of lock constraint between two output shafts. 0 to disable lock.
Lock Ratio	Input	double	Gear ratio of lock between two output shafts. Higher number means shaft 1 spins faster.
Efficiency	Input	double	Efficiency of coupling. Friction is applied to output shafts proportional to the power transmitted through the differential.
Shaft 1 Speed	Output	double	Speed of output shaft 1 in rad/s.
Shaft 1 Torque	Output	double	Net torque on output shaft 1 (in newton-meters, N m).
Shaft 1 Power	Output	double	Net power on output shaft 1 (in watts, W).
Shaft 2 Speed	Output	double	Speed of output shaft 2 (in rad/s).
Shaft 2 Torque	Output	double	Net torque on output shaft 2 (in newton-meters, N m).
Shaft 2 Power	Output	double	Net power on output shaft 2 (in watts, W).
Shaft Mass	Parameter	double	Mass of output shaft in kg
Shaft Inertia	Parameter	double	Moment of inertia of output shaft, assumed spherical in kg m²

Double Wishbone

The double wishbone component models the so called double wishbone suspension also named A-arm or single wishbone. Like other components, it has three common interfaces: Suspension Interface, Suspension Attachments and the Suspension Transforms. Because this component is generally used in pair, one for each side of a vehicle, the Double Wishbone Axle assembly make easier the use of this component.

Please, refer to the sample package for more info on these components. Also, fully tuned vehicle FED Alpha under the sample/Vehicles/FED Alpha gives an example on how to use this suspension system.

Wheel

The Wheel component models a vehicle wheel with simple suspension system. It contains a part with a cylinder collision geometry representing the wheel. It is constrained using a car wheel constraint, which allows the wheel to rotate, as well as providing an axis of travel for suspension movement, and a rotation axis to steer the wheel. It is driven by an input shaft or axle with a gear ratio constraint.

Wheel component

The geometric size and mass of the wheel is set using input fields, as well as the suspension stiffness, damping and limits. Since the starting position of the wheel might not correspond to the relaxed position, the Initial Compression can be used to specify how much the suspension is compressed in the starting position.

While the wheel has an axis for steering, this is generally managed by each vehicle topology file.

Wheel Interface

Name	IOP	Type	Description
Braking Torque	Input	double	Torque applied to brakes on wheel N m.
Steering Angle	Input	double	Steering angle applied to wheel in rad.
Radius	Input	double	Radius of cylinder representing the wheel.
Width	Input	double	Width of cylinder representing the wheel.
Mass	Input	double	Mass of wheel.
Suspension Stiffness	Input	double	Stiffness of suspension spring.
Suspension Damping	Input	double	Damping of suspension damper.
Initial Compression	Input	double	Distance that suspension starts compressed. If this is 0, when the simulation starts the suspension will compress some distance before reaching steady state.
Suspension Extension Limit	Input	double	The maximum distance from the starting point that the suspension will extend before hitting stop.
Suspension Compression Limit	Input	double	The maximum distance from the starting point that the suspension will compress before hitting stop.
Override Inertia	Input	bool	Normally wheel moment of inertia is calculated automatically from mass and geometry. If Override is true, it is instead manually defined from Axis Inertia and Off Axis Inertia.
Axis Inertia	Input	double	The inertia along the axle of the wheel. This inertia is used only if Override Inertia is true.
Off Axis Inertia	Input	double	The inertia along the two axes orthogonal to the axle. Those inertias are used only if Override Inertia is true.
Tire Type	Input	Extension* of type Tire Type	Select the Tire Type extension, which defines tire properties on various ground types.
Tire Stiffness	Input	double	Contact stiffness (N/m) of the tire in the normal direction.
Suspension Position	Output	double	Current position of the suspension. 0 at starting position, larger than 0 when extended, less than 0 when compressed.
Wheel Speed	Output	double	Linear speed at the surface of the wheel, equal to angular speed * radius.
Shaft Speed	Output	double	Speed of output shaft (in rad/s).
Shaft Torque	Output	double	Net torque on output shaft (in newton-meters, N m).
Shaft Power	Output	double	Net power on output shaft (in watts, W).

Wheel Hinged

The Wheel Hinged component models a vehicle wheel without suspension and steering system. It contains a part with a cylinder collision geometry representing the wheel. It is constrained using hinge constraint, which allows the wheel to rotate around its axle of rotation. It can be driven by an input shaft or can be free.
Use this type of component to model track idler or sprocket as well as other ground vehicles that do not require steering system and suspension like wheel loaders or rigid axle vehicle.

Wheel Interface

The wheel interface is met to set and parameterize the wheel properties.

Name	IOP	Type	Description
Radius	Input	double	Radius of cylinder representing the wheel.
Width	Input	double	Width of cylinder representing the wheel.
Mass	Input	double	Mass of wheel.
Override Inertia	Input	bool	Normally wheel moment of inertia is calculated automatically from mass and geometry. If Override is true, it is instead manually defined from Axis Inertia and Off Axis Inertia.
Axis Inertia	Input	double	The inertia along the axle of the wheel. This inertia is used only if Override Inertia is true.
Off Axis Inertia	Input	double	The inertia along the two axes orthogonal to the axle. Those inertia are used only if Override Inertia is true.
Coefficient	Input	double	Friction coefficient in the hinge constraint. F = "friction coefficient" * "constraint force outside coordinate axis".
Loss	Input	double	Loss in the friction of the hinge constraint. Limits the friction force to be: 1/loss * Shaft Speed.
Braking Torque	Input	double	Frictional torque applied to the hinge constraint.
Wheel Speed	Output	double	Linear speed at the surface of the wheel, equal to angular speed * radius.
Shaft Speed	Output	double	Speed of output shaft (in rad/s).
Shaft Torque	Output	double	Net torque on output shaft (in newton-meters, N m).
Shaft Power	Output	double	Net power on output shaft (in watts, W).

Wheel Attachments

The Wheel Attachments interface is used to defines the chassis part, the wheel parts and axis.

Name	IOP	Type	Description
Wheel Part	output	part*	Part representing the wheel.
Wheel Primary Axis	output	vector3	Revolute axis of the wheel in its local frame.
Wheel Secondary Axis	output	vectro3	Secondary axis in local frame of the wheel.
Chassis Part	parameter	part*	Part on which the wheel is attached.
Shaft Part	parameter	part*	Part that drives the wheel.

Rigid Track Extension

The rigid track extension is a dynamic extension that is used to add one or more rigid track to a vehicle topology file. This component is the only one that is implemented by a Dynamic Extension instead of an assembly.

A Rigid Track extension models a continuous track that goes over a set of few sprockets and idlers. It is assumed that Rigid Track extensions are added to vehicle topology files where a set of sprocket and idler already exist. From the perspective of the Rigid Track extension, there is no distinction between sprocket and idler so, thereafter, they are simply called wheel.

The minimal number of wheel is 2. The wheels that are set to a Rigid Track extension needs to have some prerequisites.

Wheel axle is along the y local axis of the part.
Each of the wheel axles is parallel to each other.
All wheel positions must be located on a plane.
That plane normal must be parallel to the wheel rotating axis.
Constraint that attaches the wheel to the chassis must restrict rotation along that axis. (no steering).
Constraint that attaches the wheel to the chassis must restrict its position relative to the chassis (no suspension or lateral displacement). See 3758345837
Each wheel must be attached to the same chassis part.

When adding the wheels to a Rigid Track extension, the first can be anyone but the order in which they are added is important. The next ones should follow the right hand rule, meaning, they are set consecutively making a round trip turning in counterclockwise direction with respect to the y axis of a wheel.

From a given number of wheel, the Rigid Track extension will create as many track sections as the number of wheels. For two wheels case, their will have 2 sections, one at the bottom and one at the top, such that, the two section wrap the wheels to form a continuous caterpillar. Each track section is between two wheels. When the extension creates a Track Section it generates one part and three constraints. They are added as children objects to the extension. They are indexed from 0.

Track Part_i : is a rigid body that represents the track section between two consecutive wheels.
Prismatic_i: is constraint of type prismatic that is used to guide the Track Part.
Gear: is a constraint of type gear ratio that enforce the wheel to rotate as if they were attached together by a caterpillar.
Screw: is a constraint that link the rotation of the first wheel and the translation of track part to simulate the movement of the caterpillar.

In the above, i is in the range [0,N-1] where N >1, is the number of wheels. All these parts and constraints are managed by the extension. The user can edit their field but few of them are controlled by the extension, like for instance, the mass property of Track Part.

As for extensions in general, this extension is divided in field of containers of type input, output and parameter. Here is a description of them.

Parameters

Main parameters:

Name	Type	Description
Number Wheel	int	Number of wheels to be used by the track. At least two wheels must be set. One Track Sections containers is added for each wheel. The set of wheel will be "enclosed" by a set of rigid tracks element.
Chassis Part	part *	The Chassis Part is the part where all the wheels in Tracks Wheels are attached to.

Input

Inputs are separated into three different containers.

Main inputs are applied to each sections.

Name	Type	Description
Linear Density	double	Linear mass density of the track in Kg/m.
Track Width	double	Width of track in m.
Track Thickness	double	Thickness of the track in m.
Track Material	VxMaterial*	Material assigned to the CG of the track part.
Tracks Wheels	Container of type WheelInputs	See below
Track Sections	Container of type TrackSectionInputs	See below

WheelInputs container

This container contains the set of wheels used by the Rigid Track extension. Each wheels defines its radius. There is as many WheelInputs entries as the wheel number. They are indexed from 0, to N-1.
Please, see the introduction at the beginning of this section for more details on how to proceed to add wheels to the Rigid Track extension.

Name	Type	Description
Wheel Part	part*	Pointer to a part that represent a wheel (sprocket or idler).
Wheel Radius	double	Radius of the wheel. In general, this is the same as the wheel cg radius.

TrackSectionInputs container

This container gather all the data use to parameterize one track section. There is as many TrackSectionInputs container as the wheel number. They are indexed from 0, to N-1

Name	Type	Description
Wheel 0	part*	Pointer on the first wheel of this track section. This field is read only. It is one of the wheel part set in the WheelInputs container.
Wheel 1	part *	Pointer on the second wheel of this track section. This field is read only. It is one of the wheel part set in the WheelInputs container.
Wheel 0 Radius	double	Radius of wheel 0 in meters. Generally the same value as the wheel component. This field is read only. The radius can be changed from the corresponding wheel in the WheelInputs container.
Wheel 1 Radius	double	Radius of wheel 1 in meters. Generally the same value as the wheel component. This field is read only. The radius can be changed from the corresponding wheel in the WheelInputs container.
Tracks Dimension Scale	vector3	Used to manage the size of the box cg set in the track part. When set to (1,1,1), no scale is applied, therefore the cg takes the size based on the track width, the track height and the distance between the wheels. Tip: for better contact detection, it's good practice to scale-up in z. Note that a change in the size of the cg doesn't affect the inertia of the track part.
Track Position Offset	vector3	Used to manage the position of the cg in the track part. When set to (0,0,0), there is no translatory offset and the bottom of the cg is tangent to the bottom of the wheel. Tip: For better performance, it's a good practice to move the cg a bit above the tangent point.
Enable Track Part	bool	A track part can be disabled for performance. In this case there will be no contact generated with the track part of this track section.

Outputs

The Track Sections in the output list contains a set of Track Sections indexed from 0 to N-1. Each items contains useful output data as described in the following table.

Name	Type	Description
Track Part	part*	Set to the part where sprocket/idler is attached. This field is read only. It can be accesses as a child of the extension.
Prismatic	part*	First wheel of the track. This field is read only. It can be accesses as a child of the extension.
Gear	part*	Second wheel of the track. This field is read only. It can be accesses as a child of the extension.
Screw	part*	The part that represents the rigid section of the track. This field is read only. It can be accesses as a child of the extension.
Track Part Transform	transform	World space transform of the Track Part.
Track Length	double	Length of this track section in m. This is the distance between the two wheels of this track section. It doesn't include the scaling factor, see Track Dimension Scale.
Track Speed	double	Track speed relative to the chassis in m.
Track Displacement	double	The displacement of the track since simulation start in m.
Track Tension	double	Track tension in Pa. The track tension multiplied by the cross section of the track gives the track force.
Track Force	double	Track force in the caterpillar to resist stretching in N.
Track Power	double	Power generated by the track force in W.

Hydrostatic Coupling

This component is used to model hydrostatic variable displacement pump or motor. When connected to the output shaft of a motor, it acts as a pump that converts mechanical energy to fluid pressure. When connected to the output shaft of an hydrostatic pump, it converts fluid energy into mechanical energy. The interfaces are defined as follow:

Coupling Interface

Name	IOP	Type	Description
Max Torque	Input	double	Max torque that gear constraint 'Shaft [G]' is allowed to applied
Ratio	Input	double	To control the rotational speed ratio between the input shaft speed (w_i) and the output shaft speed (w_o)
Ratio Scale	Input	double	Scaling factor applied to the rotational speed ratio
Input Shaft Speed	Input	double	w_i, the speed of input shaft from previous component
Final Ratio	Output	double	Final ratio as : w_o = RatioRatios_Scalew_i
Shaft Speed	Output	double	w_o, the speed of output shaft in rad/s
Shaft Torque	Output	double	Net torque on output shaft in N.m
Shaft Power	Output	double	Net power on output shaft in W
Shaft Mass	Parameters	double	Mass of output shaft in kg
Shaft Inertia	Parameters	double	Moment of inertia of output shaft, assumed spherical in kg m²

Vehicle Library

Vehicle Systems provides a set of finished vehicles. They are located under the assets folder of the sample package. They are provided as example and can be used as a starting point for modelling a new vehicle. See 3758345837 for more details.

The list of completed vehicle is as follow:

Car - Hatchback
Car - Hybrid
Car - Sedan
Car - SUV
Excavator
FED Alpha
Pickup Truck
Semi Truck - Single
Semi Truck - Tandem
Trailer - Flatbed
Trailer - Lowboy