User Guide for Adding Trailer as Modification

Overview

Preface

In terms of the set of files and the model itself, a trailer is the same vehicle as a car with some exceptions which will be described in this guide.

For that, we need to configure something in the files located in the folders:

datagamedatacars<My_trailer_name>;
dataphysicscars<My_trailer_name>;
exportgfxlibcars<My_trailer_name>;
exportguiccdimagesetscars<My_trailer_name>;
exportmeshescars<My_trailer_name>;
exporttexturesddscars<My_trailer_name>.

As well as the XML file of “<My_trailer_name>.xml” type located in “dataconfiguser_cars” folder.

Now let’s get down to the practical details.

1. CarProperty.ini

If you want cargo to appear on the trailer when downloading the trailer in the small cargo mode, two objects must be added to the model:

cargo denoting partial loading;
cargo denoting full loading.

The pivot of objects must be located at the origin of coordinates (0;0;0). The objects must have the names “сargo_1” and “сargo_2” for partial and full loading respectively. The names of cargo will be indicated in the configuration files.

A new section (indicated in square brackets) and several parameters indicating loads are added in CarProperty.ini located in the folder “datagamedatacars<My_trailer_name>”, where “<My_trailer_name>” is the name of your trailer:

[Cargo]
MinCargoLevel = 0.05 // Minimum loading level at which the cargo appears
CargoLevel = (max = 0.5, detail = “cargo_1”) // Maximum relative loading level for detail cargo. Maximum value = 1. detail = “cargo_1” — name of the detail-cargo in the scene with the trailer model
CargoLevel = (max = 1.0, detail = “cargo_2”)// Maximum relative loading level for detail-cargo. Maximum value = 1. detail = “cargo_2” — name of the detail-cargo in the scene with the trailer model

The “[Common]” section shows the trailer capacity in kilograms:

[Common]
MaxCargo = 700 //Maximum cargo weight used in cargo transportation

“CarProperty.ini” is the only file in the folder “datagamedatacars<My_trailer_name>” required for trailer functioning.

2. p_player_setup.ini

You can configure the trailer physical properties in this file.

In terms of the physics, a trailer is also a car, but it can be attached to the other (main) traction truck from the backside. Since the trailer should not drive itself, its design, as in life, can be greatly simplified: it may exclude the ICE, transmission, steering control, but it should include such basic components as a suspension, wheels, and a body; brakes may be included as well.

2.1. Trailer attachment points

To have a trailer attached, you should set the points of rear and front attachment for a traction truck and a trailer, correspondingly.

The connection point of the trailer to the car’s trailer hitch is indicated in the file “p_player_setup.ini” located in the folder “dataphysicscars<My_trailer_name>”.

Write the parameter in the section “[Misc]” (if there is no such section, create it):

[Misc]
TractorTrailerConnectionPoint_Front = 0.0; 0.036; -3.522 //Front attachment point is used for a trailer, which is to be attached to the traction truck (local coordinate system)

TractorTrailerConnectionPoint_Front is a point of attachment of a trailer to a vehicle hitch, where the first value is –X from the editor, the second is Z, and the third is Y.

To determine the coordinates of the connection point, create a sphere on the car model scene and position it at the location of the hitch lock:

Attachment point should be indicated also for a traction truck to which the trailer is going to be attached, e.g.:

[Misc]
TractorTrailerConnectionPoint_ForTrailer = 0; 0.0; 1.5 // Rear attachment point is used for a traction truck to have the trailer attached (local coordinate system), when attaching, it will align with the front attachment point

2.2. Weight and volume of the cargo

To load the cargo on a car or trailer, it is necessary to specify the mass center of the cargo or simply the cargo position. The common mass center of loads in the vehicle is indicated in the same section. In our case it is located between trailer axles:

[Misc]
CargoEnabled = true // Allows to load the cargo on the vehicle
CargoPosition = 0.0; 0.0; 0.0 // Position of the cargo reference point (local coordinate system [-X; Z; Y])

The volume of the trailer body is indicated in the section “[Cargo]”. The value is given in liters.

[Cargo]
CargoVolume=2700

HavokVehicleKit is responsible for simulating the physics of the car as a whole and of the suspension in particular. The car suspension can start behaving abnormally, if the cargo mass is equal to the mass of the car itself. To avoid this, part of the cargo mass can be redistributed onto the car. This would make it possible to load all necessary mass of the cargo, i.e., total mass of the car + the cargo will meet expectations.

This factor in the settings indicates that 30% of the cargo mass will be redistributed onto the vehicle, and 70% — onto the cargo on the trailer.

CargoToChasisFraction = 0.3

2.3. Rotation angle

To constrain the degree of the trailer rotation freedom with respect to the traction track, the angle constraints should be set. This is done in the Traction Truck Settings:

[Common]
TrailerRotateAngle = 115 // Maximum rotation angle of the trailer about the vertical axis (rotation to the left / right)
TrailerUpAngle = 30 // Maximum rotation angle of the trailer about the horizontal axis (rotation up / down)
TrailerTwistAngle = 30 // Maximum rotation angle of the trailer about the longitudinal axis (inclination to the left / right)

2.4. Inertial properties

It is of no small importance to set the moment of inertia for a trailer (and/or a vehicle) correctly. This makes it possible to simulate a vehicle maneuverability in a more realistic way. The moment of inertia for the cargo is obtained from the Settings of the Moment of Inertia for Chassis. These settings are relevant for both the trailer and the vehicle.

The higher the value, the more inert the vehicle when rotating along various axes. The parameters have an impact on the “rotatability” through the wheel forces, external forces, and collisions with the environment:

[Common]
m_chassisUnitInertiaYaw = 4 // The moment of inertia about the rotation axis (to the left / right)
m_chassisUnitInertiaPitch = 3 // The moment of inertia about the inclination axis (forward / backward)
m_chassisUnitInertiaRoll = 1.5 // The moment of inertia about the roll axis (to the left / right)

Multipliers of the moment of inertia for chassis of a trailer or vehicle can make the vehicle more agile and dynamic when accelerating, applying brakes, and maneuvering, if the parameter factors exceed one, or more inert, if they are below one. We recommend that you set them to 1.

In fact, m_torque[…]Factor is a force multiplier transferred to a vehicle through wheels. It does not affect the interaction through impacts with a body.

[Common]
m_torqueYawFactor = 1 // Multiplier of the moment of inertia for chassis about the rotation axis (to the left / right).
m_torquePitchFactor = 1 // Multiplier of the moment of inertia for chassis (inclination forward / backward)
m_torqueRollFactor = 1 // Multiplier of the moment of inertia for chassis about the roll axis (to the left / right)

The trailer suspension shall be set just like that of an ordinary vehicle, however, there is a peculiarity. We have to set at least two axes for a vehicle; this is a feature of HavokVehicleKit.

To make a trailer have one axis, it is necessary to configure the physics of the trailer for two axes, but change the wheels settings for the second axis by defining their function as nominal. This means to set a suspension travel to zero, define small size for wheels, and position the latter so as for them not to touch the ground; and in case they can touch the ground, to set a zero friction therefor. To do so, you need to specify the following settings in “p_player_setup.ini” file:

[Suspension] // Friction
dampingCompression_and_dampingRelaxation = 3.0 // Depreciation factor (damping)
suspension_length_0_1 = 0.3 // Height / travel of the suspension of wheels 0 and 1
suspension_length_2_3 = 0 // Height / travel of the suspension of wheels 2 and 3
suspension_strength_0_1 = 35 // Stiffness of the suspension spring for wheels 0 and 1
suspension_strength_2_3 = 0 // Stiffness of the suspension spring for wheels 2 and 3

[Wheels] // Wheel settings
m_numWheels = 4 // Total number of wheels
WheelRadius = 0.5 // Radius of physical wheels by default (to avoid specifying for each wheel)
m_wheelParams[2].m_radius = 0.1 // Radius of physical wheel 2
m_wheelParams[3].m_radius = 0.1 // Radius of physical wheel 3

As a rule, today, even small trailers are equipped with braking mechanisms. Small trailers are usually equipped with inertia/overrun brake; however, we have not implemented this type of brakes so far. Nevertheless, it is possible to configure a hydraulic or compressed air brake, which will be engaged synchronously on both the traction truck and the trailer when depressing the relevant pedal:

[Brake]
m_maxBreakingTorque_0_1 = 500 // Maximum axis braking torque
isConnectedToHandbrake_0_1 = false // If the axis is connected to the parking-brake

Settings for compressed air brakes extend the brake basic settings in “[Brake]” section.
If you need compressed air brakes, you need to assign the right type thereto:

[Brake]
Type = 2 // Compressed air brakes

You also need to specify the parameters for compressed-air parts, e.g.:

[AirBrake]
CircuitCount = 2 // Number of compressed air brake circuits, number of receivers (air tanks)
AxisUseCircuit[0] = 0 // The circuit used for compressed-air circuit 0
AxisUseCircuit[1] = 1 // The circuit used for compressed-air circuit 1
Capacity[0] = 20 // The volume of the air tank (liters) for compressed-air circuit 0
Capacity[1] = 40 // The volume of the air tank (liters) for compressed-air circuit 1
MaxPressure[0] = 8 // Maximum air pressure in the tank (standard atmosphere) for compressed-air circuit 0
MaxPressure[1] = 8 // Maximum air pressure in the tank (standard atmosphere) for compressed-air circuit 1
WorkPressure[0] = 5 // Minimum operating pressure in compressed-air circuit 0, at which the braking force reaches 100%
WorkPressure[1] = 5 // Minimum operating pressure in compressed-air circuit 1, at which the braking force reaches 100%
AirVolume[0] = 80 // The volume of air pumped for compressed-air circuit 0 at the start of driving 80/20 = 4 atm
AirVolume[1] = 160 // The volume of air pumped for compressed-air circuit 1 at the start of driving 160/20 = 8 atm
AirPumping[0] = 1 // Air pumping rate (liters per sec for each 1,000 RPM of the engine) for compressed-air circuit 0. When increasing the speed with the engine, the pumping increases.
AirPumping[1] = 2 // Air pumping rate (liters per sec for each 1,000 RPM of the engine) for compressed-air circuit 1.
AirOutgo[0] = 10 // Air consumption rate (liters) per each full brake application for compressed-air circuit 0
AirOutgo[1] = 20 // Air consumption rate (liters) per each full brake application for compressed-air circuit 1
BrakeInSpeed[0] = 5 // Braking action speed for compressed-air circuit 0
BrakeInSpeed[1] = 5 // Braking action speed for compressed-air circuit 1
BrakeOutSpeed[0] = 5 // Brake release rate for compressed-air circuit 0
BrakeOutSpeed[1] = 5 // Brake release rate for compressed-air circuit 1

3. <My_trailer_name>.xml

The mode file located in the folder “dataconfiguser_cars” must be as follows:

The parameter trailerType=”turnBuckle” determines compatibility between the car and the trailer, i. e. if the car and the trailer have different values of the parameter trailerType, the choice of the trailer will not be available for this car.

The parameter trailerConnectionPointHeight is the height of the trailer/car connection point above the ground. If the value of this parameter in the car and the trailer differs by more than 0.15, the choice of the trailer will not be available for this car.

To determine the height of the trailer connection point (given in meters), measure the distance between the trailer hitch lock and the ground (in this case the lowest point of the wheel) using the tool Helpers → Tape:

The name and description may be assigned additionally to the mod trailer. In this case, the mod file will contain the following:

<Car type = “trailer” trailerType = “turnBuckle” trailerConnectionPointHeight = “0.42” >
<DisplayName> Trailer </DisplayName>
<Description> Car trailer </Description>
</Car>

4. Physical model

When simulating the physics with 3DS Max, as with a vehicle, you can create a solid object consisting of one part or the aggregate one consisting of several parts.

If the physics of the trailer includes just one part, you should anticipate the consequences of the interaction between the trailer and traction truck. If the trailer is supposed to collide with the traction truck, you should try to do so as for the contact point of the trailer physics to keep as much distance to the attachment point as possible, otherwise, it will cause partial break of the joints and unpleasant jogging. This behavior results from the fact that the partially broken joint tends to avoid its own rupture. For that, you can configure the physics of the trailer hitch to be shortened and to never reach the traction truck. In this case, narrow objects such as pillars can pass between the traction truck and trailer.

Example of the correct physical mesh (physical model is colored red):

There is another option: to make the trailer material transparent for the traction truck material so as for them not to collide, and to specify the rotation angle constraints for simulating the collision (TrailerRotateAngle, TrailerUpAngle, TrailerTwistAngle).

If you decide to make it possible for the trailer to collide with the traction truck, but exclude the possibility of passing anything through the hitch, you can make the physics of the trailer aggregate. To do so, you need to set the hitch and the trailer body as separate parts with different materials. This will make the hitch rotate (up / down) as that of the truck trailer.

Settings for uploading the aggregate physics with different materials in “p_player_setup.ini” file:

[Common]
UseFilePhysics = true // Composite physics is used: a vehicle can consist of more than one part, and such parameters as friction, elasticity, mass center, moments of inertia, shall be set in 3ds Max model
PhysicsFiles = “meshes:cars/CustomCar/p_body.hkx” // Physical mesh path
RootBodyName = “body” // Name of the part-body of the vehicle
MaterialName = “TrailerBody” // The base material of the vehicle (by default)
BodiesMaterials = (frontDetail = “DeviceCollidable”) // Assigning materials to parts. You can specify several ones; use “,” or “;” for separation when enumerating

To simulate a really complex trailer with a moveable hitch and a swivel truck, you need to divide it into two trailers:

The first half of the trailer is a swivel truck consisting of two parts: a truck and a hitch.
The second half of the trailer is the basic part.

In fact, it will look like an “articulated” vehicle: traction truck + trailer + trailer. To make the halves of the trailers only rotate about a vertical axis between themselves, you need to set the rotation angle constraints between the first and the second halves.

This is done through the parameters of “Rotation Angle” section.

[Common]
TrailerRotateAngle = 180
TrailerUpAngle = 0
TrailerTwistAngle = 0

5. Dust and splash clipping

A new item must be added in the trailer model to clip particles of dust and splash. For our trailer, the item is as follows:

The shader “ParticleClippingDepthShader” must be set to the item. The item must be convex, with its normals facing outward. Particles will be hidden inside the item.

6. Limitations

When creating a trailer, take into account the following limitations:

Correct operation of the trailer physics is guaranteed for two-axle trailers (with two wheel pairs) only. Single-axle trailers may have abnormal performance.
To ensure correct interaction with the game environment, it is important that the trailer (including the tow hitch) is no more than 5.1 meters long and 2.3 meters wide.

7. Mode publication in the Steam workshop

To publish the trailer in the Workshop, start the Free Driving session and select the car and the connected trailer in the menu “Transport”.
After the free driving session has loaded, call the game console by pressing the key ~ (tilde) on the keyboard. Enter the command “steam_publish_car” in the window that opens and press “Enter”.

You can give a description of the change in the published version in the field “Change notes”.
Select “Trailer” in the drop-down list “Type”:

The drop-down list “Visibility” allows you to select mode visibility (“Public”, “Private” or “Friends only”).

When you have completed the actions described above, press “Publish” to publish the mode in the Workshop. The field “Status” will show the mode publication progress and notifications of successful completion or an error.

City Car Driving Guide