If you want an offline copy, you can download this full guide in PDF format from here (in English or in Russian).
1. Organization of Files
All file names must contain only small letters, digits, and “_”.
1.1. Files of a Truck
- .../meshes/trucks/truck_example.fbx - contains:
- Truck meshes
- Truck skeleton
- Collision meshes
- .../meshes/trucks/truck_example.xml - contains:
- Paths to truck textures and descriptions of their properties (Blending, AlphaKill, TwoSided, snow cover parameters, etc.)
- description of shaft mounting points
- MaterialOverrides - info about color customization
- .../classes/trucks/truck_example.xml - contains all information on truck behaviour: description of the physical model dynamics, types and sizes of wheels used by the truck, descriptions of available suspensions and engines, info on lighting (location of lights, their brightness, color, shape, etc.), driver position, position and direction of the exhaust pipe, descriptions of available addons and trailers, price of the truck, and so on.
- .../classes/suspensions/s_truck_example.xml - description of the suspension
- .../classes/gearboxes/ - description of gearboxes (files of gearboxes are typically not tied to a particular truck, but are common for the particular class of trucks).
- .../classes/engines/ - description of engines (files of engines are typically not tied to a particular truck, but are common for the particular class of trucks).
1.2 Files of Wheels
Wheels of a truck include tires and rims and must contain both of these entities.
Wheels of trailers and semi-trailers may be created using the old scheme where a wheel is a single entity (similarly to the first Mudrunner).
The old scheme is the following:
- fbx of the wheel, .../meshes/wheels/wheel_example.fbx
- xml of a mesh, .../meshes/wheels/wheel_example.xml, which contains information on textures and radius of the non-deformable part of the wheel RubberRadius (wheel rim radius).
- xml of a class, .../classes/wheels/wheel_example.xml, which contains a description of the physical properties of the wheel (radius, width, friction, rigidity, etc.)
The new scheme describes not a wheel, but the particular type of the wheel. Wheels of this type may have different tires and rims. I.e., after selection of any rim from a wheel type, any tire from the same wheel type will fit with it well (and there will be no gaps or intersections of geometry):
- Set of fbx files for tires and rims .../meshes/wheels/
- Set of xml files for meshes of tires and rims that contain information on textures:
- xml file of a class, .../classes/wheels/wheel_example.xml,
which contains the description of the physical properties of this type of wheels. This file describes all tires and rims of this type and their properties.
1.3. Files of Truck Addons
In a wide-sense, an addon to a truck is anything that can be installed to it: visual upgrades (modification of exhaust pipes, sun visors, lamps, and so on), functional upgrades (snorkels, bumpers, bodies, cranes, and so on), and trailers.
In the strict sense, trailers and semi-trailers can exist on the scene separately from the truck and are not addons. Roughly speaking, a trailer or semitrailer is a truncated truck, which contains no engine, no driver, etc.
The organization of files of addons is absolutely similar to the organization of truck files. In principle, files of addons may be located in the folder of truck files (as in Mudrunner 1). However, for ease of use, addon files are stored in separate subfolders.
Thus, addons that are common for all trucks or several trucks (e.g. fifth wheels, bodies, cranes, and so on) are stored in the addons subfolder: .../classes/trucks/addons
Trailers and semi-trailers are stored in the trailers subfolder: .../classes/trucks/trailers
Individual addons of a truck are stored in the <name_of_truck>_tuning folder: .../classes/trucks/truck_example_tuning
2. Fbx file structure
SnowRunner uses the Fbx format to store information about the geometry, skeleton, and collision meshes of a truck, trailer, addon, or wheel.
2.1. Coordinate axes
In the game, the truck is oriented along the OX axis. The OY axis is pointing up. The OZ axis is pointing to the left.
This orientation corresponds to the (x, y, -z) axes in Maya:
And, in 3DS Max, to the (x, z, y) axes:
In Blender, the axes are the same as in 3DS Max. So, the orientation of the game corresponds to the (x, z, y) axes orientation in Blender:
Thus, to correctly export your truck to the Fbx file from your 3D editor, the forward axis of your truck should be looking in the direction of the OX axis during the export.
And, to correctly perform exporting, Export Settings in your 3D editor should be exactly the same as shown on the screenshots in the "Exporting to Fbx: 3ds Max, Maya, and Blender" guide, in the section corresponding to this 3D editor.
Moreover, after exporting, when you will be specifying truck properties in XML, you should take into account the difference in the orientation of the axes, which was described above.
If the coordinates of the center of the wheel of your truck in 3Ds Max or Blender are (1; 2; 3), then in the XML description of this wheel you need to specify "(1; 3; 2)" as the value of the Pos attribute:
Pos="(1; 3; 2)"
2.2. Requirements for objects in the Fbx file
All objects and meshes must have identity scale. For example:
- in Maya - it corresponds to the (1, 1, 1) scale,
- in 3DS Max - to the (100, 100, 100) scale.
- in Blender - to the (1, 1, 1) scale.
Ensure that the root bone and all truck meshes have identity rotation (0, 0, 0).
A truck, addon, and semi-trailer can have only one root bone. All other bones must be lower in the hierarchy.
A truck or semi-trailer must have at least one physical bone. The physical bone must have a collision mesh. All bones and meshes of trucks and semi-trailers must have skin modifiers.
Addons may have no bones at all (e.g., small addons such as lamps, posters, and other addons that do not need a collision). If an addon has bones, then these bones must have skin modifiers and there must be at least one physical bone.
Wheels have no bones or collision objects. Wheel collision is defined in XML.
2.3. Special meshes
Each truck with a cab has the _windshield and _cockpit meshes.
Glasses that are visible from the first-person camera. This glass is a duplicate of the glasses that are visible from the outside, with the inverted normals. In addition, this mesh is made a bit more high-poly, since water and dirt stick to the glass on a per-vertex basis.
Water cut-off area. The image below shows a poorly configured _cockpit. The arrows show the parts of the wipers that are inside the _cockpit mesh. Visually, they seem to be inside the cab.
2.4. Truck meshes
The number of truck meshes is not limited. But each separate mesh causes a separate draw call, which reduces performance. On the other hand, the engine does not support too many triangles in the same mesh. (The number of triangles is calculated during export from Fbx and is different for each mesh, maximum is near 65,000 triangles.) So, we have to look for a balance.
2.4.1. lp_cab, hp_cab
We recommend making the cab more detailed for a first-person camera, than for an external camera. If a mesh has the lp_ prefix (lp = low poly), then it is visible only from an external camera. Meshes with the hp_ prefix (high poly) are visible only from a first-person camera.
In the Fbx file, any textures can be assigned to the truck mesh. Textures must have correct names: their names can contain Latin characters and digits and must have no special characters (except “_”) and no spaces. The system takes only the name of a texture from the Fbx file. All properties of a texture are described in the XML file of the mesh.
The fewer textures are assigned to the truck, the better the performance is.
WARNING: All textures of materials of the mod must adhere to the specific naming scheme, see the "7.2. <Material>" section for details. This naming scheme is necessary to enable streaming for textures of the mod, which may be essential. Particularly, mods with wrong naming of textures result in memory leaks on consoles and will not receive an approval for them.
You may use the same texture maps on different shapes. But, for example, if one shape is inside the cab and the other is outside the cab, then you should take this into account at the stage of creating the Fbx file. Particularly, in this case, you should create two materials with different names in the Fbx file, since their parameters will be different in XML (e.g. the parameters responsible for snow cover). You can use one texture for all truck meshes, but the Fbx file should have as many materials as the number of different sets of parameters in the XML description.
For example, you can have one .tga file of texture. And, if you assign one material to the truck in Maya, everything will be looking OK there (not in the game). However, in the XML file, there may be a necessity to define different parameters for different parts of the truck (e.g. enable or disable snow cover). And you will not be able to do this if you have assigned one material for all parts of the truck. So, you will need to duplicate the material in Maya, rename the second copy of the material there, and assign this second material to the necessary parts of the truck. In this case, you will be able to define different values of parameters in the XML for it.
2.6.1. Physical bones
Bones that are included in the Havok simulation. I.e., the bones that must respond to gravity, collide, have friction, and so on. All bones in the physical model must have collision meshes. For convenience, we use the NameOfBone_сdt naming, which means that this bone has a collision mesh.
126.96.36.199. Collision meshes
The name of the collision mesh must begin with “cdt”. In general, a collision mesh can have any shape. It can be a closed figure or a two-dimensional surface.
A single physical bone can have multiple collision meshes.
From the performance point of view, the best form of collision mesh is a cube.
It is desirable that the collision mesh is a convex figure. We recommend that due to the fact that convex-concave shapes can cause crashes (if a small collision environment object gets inside, it can “fall through” inside the collision mesh).
2.6.2. Non-physical bones
The behavior of these bones is not directly related to Havok physics. However, it depends on the position of the physical or non-physical bones that they are attached to or on the position of the wheels. These bones do not have collision meshes and cannot affect the behavior of the bones of the physical model.
Truck axle. For a dependent suspension, the position of the axles along the OY axis is calculated as an average between the two nearest wheels, the rotation angle is calculated from the vector connecting these wheels.
If the Y coordinate of the axel bone does not coincide with the coordinate of the nearest wheel described in the XML of the truck, then you can get the unexpected result in the game: the bone will be located between the wheels and the skinned mesh will be deformed.
The steering rack always consists of three bones: the bone of the rack, the bone of the left hub, and the bone of the right hub.
The behavior of each bone (of hubs and the rack) is controlled by the rotation of the wheel that is closest to it.
The bone of the rack moves along the arc calculated from the position of the nearest wheel and the length of the rack itself. (Half of the length of the rack is specified in the XML of the truck by the value of the
Hub bones rotate with the nearest wheels. However, the rotation pivot of the hub does not match the rotation pivot of the wheel. Therefore, the wheel should not just rotate, but also move along the circle circumscribed around the attachment point of the hub. The parameter
SteeringJointOffset in the Wheel tag in the XML of the track is responsible for this offset.
If the truck has an independent suspension (there is no common rack), then the bone of the rack still needs to be created - to ensure the correct display of the behavior of the hubs. And, since all bones must have skin modifiers, you also need to add this bone to the skin modifier of any mesh of the truck.
As an example, consider a setup of the hydraulics of the crane.
Here, only two bones are involved in physics (BoneRotationBase_cdt, BoneArm1_cdt).
To implement the operation of a hydraulic piston, we need two chains of bones with inverse kinematics. BoneRod1, BoneRod2 and BonePistonBase, BonePiston.
The BoneRod1 bone is attached to the BoneRotationBase_cdt by the Hinge constant. The BoneRod2 bone is attached to the BoneRod1 by the Hinge constant. And, the locator (in Maya terms) of inverse kinematics is attached to the BoneArm1_cdt bone. Thus, their behavior is completely determined by the position of the physical bones.
The hydraulic piston is similarly organized, but the inverse kinematics locator is attached not to the physical bone, but the bone from the first chain - BoneRod2.
Some bones are described in the XML of the truck as "Shakers". They are needed, for example, to rattle the exhaust pipe or to provide a vibration of a running engine.
The bones, which are described in the XML of the truck as Rotators, will help to rotate the fan or the emergency light bulb.
3. ХМL Description of a Truck
3.1. XML of the Mesh (/meshes/trucks)
This XML file contains info on textures of a truck or addon. Along with it, it may contain some specific information, such as the following: description of shaft mounting points, snow cover parameters, and other information that is related to the mesh.
3.2. XML of the Truck Class (/classes/trucks)
This file contains all information on the behavior of the truck in the game engine. Here is a partial list of what is described there:
- Description of the type of the object - a truck, an addon, or a trailer.
- Description of the Havok physical model (characteristics of the interaction of physical bones with each other and with the environment)
- Description of the behavior of bones that are not related to the physical engine: shakers (vibrations, the intensity of which depends on current “engine power”), bones of inverse cinematics (the behavior of which depends on positions of other bones, but not from the physical simulation), and so on.
- Assignment of control buttons
- Positions and description of characteristics of light sources
- Available engines, suspensions, gearboxes
- Whether or not the truck has the differential
- Types, sizes, and positions of wheels
- Types of the wheel drive
- Descriptions of cast shadows
- The behavior of the steering wheel and wheels that are connected to it
- Position and direction of airflow and the exhaust
- Position of the driver
- Position of external camera and position of the first-person camera
- Damage characteristics for the engine and fuel tanks
- Positions of the addons and their interactions with the truck and with each other
- Length of the winch
- Attachment points for the winch
- Attachment points for the crane rope
- Price of truck
- For trucks: Positions of cameras in the garage; for addons: the camera that is active when the addon is selected
- Description of the truck model on the map
3.3. XML of the Suspension Class (/classes/suspensions)
This file contains a description of the suspensions that are available for the particular truck. Typically, there are two of them: default and raised (e.g.
Here you can specify:
- height and stiffness of the suspension
- maximum detachment of wheels from the truck in case of a broken suspension
- value of DamageCapacity
- value of CriticalDamageThreshold
- value of BrokenWheelDamageMultiplier
- price of the suspension
- parameters for unlocking this suspension in the game
3.4. XML of the Engine Class (/classes/engines)
DamageCapacity and other engine damage parameters, fuel consumption coefficient, torque strength, and so on.
3.5. XML of the Gearbox Class (/classes/gearboxes)
Information on the gearbox damage, fuel consumption coefficient, info on gears.
3.6. XML of Material Customization (/classes/customization_presets/customization_preset.xml)
This file contains color customization presets for the truck.
4. Description of Wheels
There are two ways to create a wheel:
- You can create the wheel as a whole. I.e., in this case, the tire and the rim are the single entity.
- You can create a particular sort of a wheel (i.e. a set of wheels), which will contain several interchangeable tires and rims.
Fbx и XML files of meshes for wheels, tires, and rims are located in the following folder: /meshes/wheels
XML files of the classes of the wheel or the set of the wheels are located in the following folder: /classes/wheels
4.1. A wheel as a single entity
The Fbx file of the wheel contains the whole geometry of the left wheel. Which part of the wheel is a tire (that can be deformed) and which part is the rim - is determined by the parameter in the XML file of the mesh of the wheel. The XML of the class contains all characteristics of the wheel, such as the following: friction, tire stiffness, wheel mark, the mass of the wheel, radius and width of the wheel in Havok.
If the wheels of the truck are described in this way, then they cannot be changed. Moreover, in this case, there are no tire and wheel selection options in the menu of the garage.
4.2. A wheel as a set of tires and rims
A single Fbx file contains either one or two tires, or one or two rims. When geometry is created for the wheels that are single for all axes of the truck (as on most scouts), then the Fbx file will contain only one tire (named “tire”) or only one rim (named “rim”). In the case of twin wheels (typically, rear wheels of a truck), the Fbx file will contain two tires or two rims.
Sometimes, the vehicle has mixed types of wheels. E.g., the truck can have twin rear wheels and single front wheels.
In this case, the Fbx contains both geometry of the single wheel tire (rim) named as “tire_front” (“rim_front”) and the twin wheel geometry named as “tire_back” (“rim_back”).
In this case, these names (“tire_front”/“rim_front” and “tire_back”/“rim_back”) for these elements are strictly necessary, since this allows us to correctly determine the type of the wheel and use the same tread pattern or disk geometry during customization.
XML of the mesh contains only the information on the materials.
XML of the class contains a description of characteristics of all tires and rims that are available within this type of wheel.
To continue, please refer to:
- Part #2 of this guide - for general aspects of the XML structure (Chapters 5-6).
- Part #3 - for description of tags and attributes used for Meshes and Trucks (Chapters 7-8).
- Part #4 - for tags and attributes used for Suspensions, Engines, Gearboxes, Wheels, and Addons (Chapters 9-14).
- Part #5 - for tags and attributes used for the creation of custom skins and colorization (Chapter 15).