Truck Description File

From Rigs Of Rods

(Difference between revisions)

Revision as of 01:08, 10 November 2006

This file is in text format. It contains all the structural, physical and visual parameters defining a truck. It is parsed by a very crude parser, so stick to the syntax, or expect crashes. Some keywords seems not logical, this is due to the fact that I did not know where I was going when I started this project. So be warned that this stuff is not foolproof. It is decomposed in sections, each section is announced by a keyword (except the title). Comments can be put anywhere by putting a ";" as the first character of the line. Node coordinates are always:

X: front to back
Y: bottom to top
Z: right to left

See Truck Concepts to understand the building philosophy. I recommand the following method of construction:

Draw the blueprint of your truck on a drawing paper. Mark the nodes, and write their number.
Edit your truck file and put the title, globals, engine, cameras, nodes and beams section.
Run the game to see how it goes. If you forget some beams the truck will fold on itself!
When the chassis seems good, add wheels, suspensions, direction and test-drive
When the truck is sound, do the bodywork and texture, and mark most beams as invisible (displaying too much beams have a large performance impact)

To see a simple truck file example, see this Step by step truck construction.

Before be start, let ask an important question: Is it a truck or is it a plane? or what makes a truck a truck and a plane a plane. Simple:

A truck is a description file containing an engine section
A plane is a description file containing a turboprops section

Also, notice that:

You should not have both an engine section and a turboprops section in the same file
If you have neither, then you are making a load, and the file extension should be .load (see Creating a Load)
It is legal to have a wings section on a truck (e.g. to add aerodynamic spoilers for stability).

We go thru the sections. Order is important, so stick to this order.

Title

This section is the only that is not introduced by a keyword. It is the name of the truck, and it must absolutely be the first line of the file. e.g.

My nice truck

Globals

This section defines some global parameters, in only one line containing: the global dry mass (in kg), the global cargo mass (mass of the nodes marked "l") and the name of the material that Ogre will use to texture the truck. This must coincide with the material name given in the Material File. If you don't know, or your truck is not textured yet (no submesh section) you can reuse any existing material, like tracks/semi for example.

globals
;dry mass, cargo mass, material
10000.0, 1000.0, tracks/semi

Globeams

This section is very special and should not be used for most designs. It was created to make the bridge. It allows you to alter the default mechanical and visual beam properties. The parameters are: default stress at which beams deforms (in Newtons), default stress at which beams break, default beams diameter (in meter), default beams material.

globeams
500000, 1000000, 0.5, tracks/beam

Engine

The engine section contains the engine parameters. You should not fiddle too much this. The interesting parameter is the torque (3rd one) that defines the engine power. You don't want to use this section if you want to do a plane or a load.

engine
;min rpm, max rpm, torque, differential ratio, rear gear, first, second, third, fourth, fifth, sixth...
1000.0, 1500.0,  8000.0, 2.00, 10.85,  13.86, 9.52, 6.56, 5.48, 4.58, 3.83, 3.02, 2.53, 2.08, 1.74, 1.43, 1.20, 1.00, -1.0

UPDATE: As of 0.29 you can have a truck with no engine! you just cant use hydros, commands, or a dashboard.

Cameras

This section is important. It helps to position the truck in space, by defining a local direction reference. For example this is used to measure the pitch and the roll of the truck. The three parameters are node numbers (defined in the next section). The first if the reference and may be anywhere, the second must be behind the first (if you look at the front of the truck, it is hidden behind the first), and the third must be at the left of the first (if you look to the right of the truck, it is hidden by the first)

cameras
;center,back,left
0,2,1

Nodes

With this section begins the structural description. Each line defines a node. The first parameter is the node number, and must absolutely be consecutive. The three following parameters are the x,y,z coordinates, in meter. You can attach an optional option to a node by adding a single character. Recognized options are:

"l": this node bears a part of the cargo load
"f": this node has extra friction with the ground (usefull for feets)
"x": this node is the exhaust point (requires a "y" node)
"y": exhaust reference point, this point is at the opposite of the direction of the exhaust
"c": this node will not detect contact with ground (can be used for optimization, on inner chassis parts)
"h": this node is a hook point (e.g. the extremity of a crane)
"e": this node is a terrain editing point (used in the terrain editor truck)
"b": this node is assigned an extra buoyancy force (experimental)

nodes
;id,    x,    y,    z,     options
;main chassis
  0, 0.00, 0.75, 0.66
  1, 0.00, 0.75, 1.84
  2, 0.63, 0.75, 0.66
  3, 0.63, 0.36, 0.66,l
  4, 0.63, 0.75, 1.84
  5, 0.63, 0.36, 1.84
  6, 1.48, 0.75, 0.66,l
  7, 1.48, 0.00, 0.66
  8, 1.48, 0.75, 1.84,c
  9, 1.48, 0.00, 1.84,x
 10, 2.33, 0.75, 0.66,y
 11, 2.33, 0.00, 0.66

Fixes

Fixes are nodes that are fixed in place. That means that once put in place in the terrain, they will never move, whatever happens. This is usefull to make fixed scenery elements from beams, like bridges. Just add the node number that you want to fix.

fixes
2
3
12

Beams

This section defines all the beams connecting nodes. Each line describes a beam. The two first parameters are the node number of the two connected nodes. Order has no importance. There is an optional 3rd parameter, composed of a single character. Recognized options are:

"i": this beam is invisible. Very usefull to hide "cheating" structural beam, or to improve performances once the truck is textured.
"r"; this beam is a rope (opposes no force to compression)

beams
0,1
2,4
3,5,i
6,8,i
7,9
10,12,i
11,13,i

Rollon

Enables collision between wheels and the textured surfaces of a truck.

rollon

Shocks

Shocks can be seen as tunable beams, usefull for suspensions. Parameters are: the two nodes connected by the shock, the spring factor (the stiffiness), the damp factor (to adjust the amount of rebound: the best value is given by 2*sqrt(suspended mass*spring)), the shortbound and the longbound factors that defines the amount of deformation the shock can support (beyond, it becomes rigid as a standard beam) when shortened and lenghtened, the last parameter is precomp, that allows to compress or depress the suspension (leave it to 1.0 for most cases). You can make the shocks stability-active with optional parameters:

"l" to make a left-hand active shock.
"r" to make a right-hand active shock.
"i" to make the shock invisible (AVAILABLE FROM VERSION 0.29).

shocks
;critical damp=2*sqrt(mass*spring)
;id1, id2, spring, damp, shortbound, longbound, precomp
36,6,  500000,100000, 0.3, 0.3, 1.0
37,8,  500000,100000, 0.3, 0.3, 1.0,l
38,2,  500000,100000, 0.3, 0.3, 1.0,r

Hydros (direction)

The hydros section concerns only the direction actuactors! They are beams that changes of length depending on the direction command. The parameters are two node numbers and a lenghtening factor (negative or positive depending on wether you want to lenghten or shorten when turning left or the contrary)

hydros
43,37,-0.2
45,37,0.2
46,36,0.2
48,36,-0.2

Commands (hydros)

The commands section describes the "real" hydros, those you command with the function keys. They are like beams, but their length varies depending with the function keys you press. The parameters are the two node numbers, a speed rate (how fast the hydro will change length), the shortest length (1.0 is the startup length), the longest length (1.0 is the startup length), the number of the shortening function key and the number of the lengthtening function key (both between 1 and 12). You can have several hydro commanded with the same function keys, or any other combination. You can add the optional flag "i" to make the hydro invisible.

commands
;id1, id2, rate, short, long, keys, keyl
10,91,0.1,1.0, 7,   1, 2, i
12,93,0.1,1.0, 7,   1, 2, i
14,90,0.1,1.0, 7,   1, 2
16,92,0.1,1.0, 7,   1, 2
114,122,0.2,1.0, 19,   3, 4
115,123,0.2,1.0, 19,   3, 4
126,132,0.1,0.1, 1.0,   5, 6

Forwardcommands

Forwards the commandkeys pressed while riding a truck to loads in close proximity. It is used to remote control the commands of a load. The load must have the "importcommands" tag.

forwardcommands

Importcommands

Enables a load to receive commandkeys from a manned vehicle in close proximity. The controlling vehicle must have the "forwardcommands" tag. The load only receives the keys that are pressed by the player, it must contain a commands section. Commands section for loads is defined in the same manner as in manned trucks.

importcommands

Contacters

The contacters section lists the nodes that may contact with cab triangle. This concerns only contacts with other trucks or loads. You can easily omit this section at first.

contacters
34
18
20
22
24
26
28
30
32

Help

The help section gives the name material used for the help panel on the dashboard. This material must be defined elsewhere in the MaterialFile. This is optional.

help
tracks/semihelp

Ropes

Ropes are special beams that have no compression strength (they can shorten easily) but have standard extension strength, like a cable or a chain. They have also another particularity: the second node can "grab" the nearest reachable ropable node with the 'O' key. Standard use is to use a chassis node as the first node, and a "free" node as the second node (free as in not attached by any other beam). The best example of this are the chains of the multibennes truck.

ropes
;order is important: root->end
116,134
130,136
116,135
130,137

Ties

Ties are also special beams that have no compression strength (they can shorten easily) but have standard extension strength, like a cable or a chain. As the Ropes, they grab the nearest reachable ropable node with the 'O' key. But there is a twist: unlike the ropes, they disappear when not attached (because they have no extremity node at rest) and they automatically shorten until the extension forces reaches a thresold. They are very usefull to solidly strap a load to a chassis. The parameters are the number of the root node (the starting point of the beam), the maximum reach length, the rate of auto-shortening, the shortest length possible, and the last parameter... well... is probably not very usefull and should be kept as 1.0... You can make a tie invisible with the "i" option.

ties
;root, max len, rate, short, long
58, 1.5, 0.5, 0.3, 1.0
62, 1.5, 0.5, 0.3, 1.0
59, 1.5, 0.5, 0.3, 1.0
63, 1.5, 0.5, 0.3, 1.0

Ropables

This section lists the nodes that can be catched by ropes or ties. Good use is to define some ropable nodes at the front and back of the truck to allow towing the truck.

ropables
0
1

Wheels

This section is important, it defines the wheels! The order in which the wheel are declared is important: each consecutive pair of wheel is grouped into an axle. Parameters are:

radius (in meter)
width (in meter)
number of rays
the numbers of two existing nodes that defines the wheel axis (the second node must have a larger Z coordinate than the first)
the number of a special rigidity node (see explanation about Axle Rigidity) or 9999 if it is not used
is the wheel braked (1) or not (0)
is the wheel propulsed (1) or not (0)
the number of a reference arm node for this wheel. This is where reaction torque is applied to the chassis. Should be on the rotation axis of the suspension arm.
mass of the wheel (in kg)
spring factor of the wheel : the stiffiness of the wheel
damp factor : the reboundiness of the wheel
face material and band material (and no quote between them) if you don't know, use "tracks/wheelface" for the face and "tracks/wheelband1" for single wheel or "tracks/wheelband2" for dual mounted wheels.

wheels
;radius,width,numrays,node1,node2,snode,braked,propulsed, arm, mass, spring, damp, facemat bandmat
0.54, 0.40, 12, 35, 36, 9999, 1, 0, 3, 200.0, 800000.0, 4000.0, tracks/wheelface tracks/wheelband1
0.54, 0.40, 12, 37, 38, 9999, 1, 0, 5, 200.0, 800000.0, 4000.0, tracks/wheelface tracks/wheelband1
0.54, 0.80, 12, 39, 40, 41, 1, 1, 25, 400.0, 800000.0, 4000.0, tracks/wheelface tracks/wheelband2
0.54, 0.80, 12, 41, 42, -40, 1, 1, 23, 400.0, 800000.0, 4000.0, tracks/wheelface tracks/wheelband2

Cinecam

This define the position of the in-truck cam. It is a special node suspended to eight chassis nodes. The parameters are the 3 coordinates of the point and the 8 nodes numbers to which it is binded.

cinecam
;x,y,z,bindings
0.66, 2.0, 1.8, 75,76,77,78,73,74,53,54

Flares

This defines where the light flares will be. It is positionned relative to 3 nodes of the chassis. One node is the reference node, and the two others define a base (x,y). So the flare is in the plane defined by the 3 nodes, and is placed relative to the reference node by adding a fraction of the vectors ref->x and ref->y. The three first parameters are the 3 nodes numbers (rex,x,y) and the two next gives what amount of ref->x and ref->y to add to displace the flare point (these two should be logically between 0 and 1, or else that means you use the wrong base triangle and if the body flexes too much the flare will not stick to the body correctly).

flares
;ref,x,y,offsetx,offsety
51,1,79, 0.23, 0.50

Props

This allows you to "stick" any 3D mesh to a triangle of points of a truck. You can use it to stick air intakes, horns, seats, dashboard, bumbers, whatever to the truck (note that there will be no collision detection of these objects). They work the same way as the flares. It is positionned relative to 3 nodes of the chassis. One node is the reference node, and the two others define a base (x,y). So the prop is positionned relative to the plane defined by the 3 nodes, and is placed relative to the reference node by adding a fraction of the vectors ref->x and ref->y. Additionnally, you can displace the prop along the normal to the plane. The three first parameters are the 3 nodes numbers (rex,x,y) and the three next gives what amount of ref->x, ref->y and normal to add to displace the prop (the first two should be logically between 0 and 1, or else that means you use the wrong base triangle and if the body flexes too much the flare will not stick to the body correctly, the third is normalized, in meter). The next 3 parameters are rotation angles to apply to the mesh (in each 3 axis), and the last is the name of an Ogre3D mesh object. Note that meshes with the name beginning with "dashboard", "leftmirror", "rightmirror", "seat", "beacon", "pale" and "spinprop" are reserved as they employ some magic to work. The first "seat" mesh is made translucent, so it should be the driver's seat.

props
;ref,x,y,offsetx,offsety,offsetz,rotx,roty,rotz,mesh
93,95,92, 0.50, 0.37, 0.0, 90, 0, 0, airintake.mesh

Submeshes

This last part defines the most visible part of the truck: the body. It will dress the chassis with solid triangles. You must define each body panel (a continuous almost-flat section) in a different submesh section, in order to have sharp body angles, and to simplify texturing. A submesh has two subsection: the texcoords, that places nodes of the submesh on the texture image (coordinates between 0.0 and 1.0) , and then the cab subsection, that draws the triangles, with triplets of node numbers. The nodes used in the cab subsection must be present in the texcoord subsection. The order in which the three points forming the triangles is given is important, as its winding defines in which direction it will be visible. The winding must be counterclockwise to be visible (IIRC). There is an optional flag to the cab subsection: if you add "c" to the triangle, this triangle will be a contact triangle, that can contact with contacters nodes. mcreed has contributed a cool Texturing Tutorial that describes how to fill the submesh and cab parts of the truck file.

When the tag "backmesh" is added, the triangles backsides of the submesh will be black instead of see-through.

;cabin top
submesh
texcoords
75, 0.172, 0.334
76, 0.172, 0.665
77, 0.291, 0.334
78, 0.291, 0.665
cab
75,76,78
75,78,77

;cabin back
submesh
texcoords
77, 0.291, 0.334
78, 0.291, 0.665
53, 0.422, 0.334
54, 0.422, 0.665
6, 0.422, 0.334
8, 0.422, 0.665
cab
77,78,54
77,54,53
53,54,8,c
53,8,6,c
backmesh

Wings

This section declares parts of the chassis as wings, and that they should bear aerodynamic forces. Each line of this section designs a wing segment, that is a homogeneous part of a wing. You can (and you should!) make a plane's wing from several contiguous wing segments. Rudder and elevators are also made with one or more wing segments. Each wing segment is bounded by 8 nodes, that defines the "bounding box" of the wing, specifically its span, chord and thickness. You must ensure that these nodes are properly interconnected by beams to ensure the structural integrity of the wing. Notice that it is VERY IMPORTANT to declare contiguous wing segments (i.e. that shares nodes) IN SEQUENTIAL ORDER FROM RIGHT TO LEFT, and you should avoid cutting a wing in two at the fuselage, but make the whole wing continuous across the fuselage because it helps to compute whole-wing effects like induced drag and other things like wing lights. A very important aerodynamic parameter is the wing airfoil. The airfoil is the tear-like shape of the wing, and its exact geometry is very important for the characteristics and performances of real-world wings. RoR uses precomputed performances curves from standard airfoils, interpolated from wing tunnel tests. These curves are stored in .afl files. Standard aifoils provided in RoR are:

NACA64.1.412: actual airfoil of the wing tip of the Hercules C-130
NACA64.3.618: similar airfoil to the wing root of the Hercules C-130
NACA0009: standard symmetrical airfoil, good for rudder and elevators
Clark-Y: used for propellers, but is also very popular for main wings

You can get more airfoil from the popular X-Plane flight simulator. RoR is compatible with X-Plane .afl, but you must convert their end-of-line style from MACOS to Windows using an advanced text editor, or RoR will crash.

The wings parameters are:

Front left down node number
Front right down node number
Front left up node number
Front right up node number
Back left down node number
Back right down node number
Back left up node number
Back right up node number
Texture X coordinate of the front left of the wing (in the texture defined in "globals")
Texture Y coordinate of the front left of the wing (in the texture defined in "globals")
Texture X coordinate of the front right of the wing (in the texture defined in "globals")
Texture Y coordinate of the front right of the wing (in the texture defined in "globals")
Texture X coordinate of the back left of the wing (in the texture defined in "globals")
Texture Y coordinate of the back left of the wing (in the texture defined in "globals")
Texture X coordinate of the back right of the wing (in the texture defined in "globals")
Texture Y coordinate of the back right of the wing (in the texture defined in "globals")
Type of control surface: 'n'=none, 'a'=right aileron, 'b'=left aileron, 'f'=flap, 'e'=elevator, 'r'=rudder
Relative chord point at which starts the control surface (between 0.5 and 1.0)
Minimum deflection of the control surface, in degree (negative deflection)
Maximum deflection of the control surface, in degree (positive deflection)
Airfoil file to use

wings
;main wing
28,22,29,23,18,20,19,21, 0.509, 0.999, 0.555, 0.751, 0.752, 0.999, 0.752, 0.751, a, 0.75, -24, 24, NACA64.1.412.afl
26,28,27,29,16,18,17,19, 0.804, 0.711, 0.818, 0.617, 0.999, 0.711, 0.999, 0.617, f, 0.75, -30, 0, NACA64.1.412.afl
90,26,25,27,14,16,15,17, 0.783, 0.844, 0.804, 0.711, 0.999, 0.844, 0.999, 0.711, f, 0.75, -30, 0, NACA64.3.618.afl
 0,90,24,25, 4,14,13,15, 0.764, 0.933, 0.784, 0.844, 0.999, 0.933, 0.999, 0.844, f, 0.75, -30, 0, NACA64.3.618.afl
 2, 0,46,24, 6, 4,12,13, 0.756, 0.999, 0.764, 0.933, 0.999, 0.999, 0.999, 0.933, n, 1.0, 0, 0, NACA0009.afl
44, 2,45,46,30, 6,31,12, 0.783, 0.844, 0.764, 0.933, 0.999, 0.844, 0.999, 0.933, f, 0.75, -30, 0, NACA64.3.618.afl
42,44,43,45,32,30,33,31, 0.804, 0.711, 0.783, 0.844, 0.999, 0.711, 0.999, 0.844, f, 0.75, -30, 0, NACA64.3.618.afl
40,42,41,43,34,32,35,33, 0.818, 0.617, 0.804, 0.711, 0.999, 0.617, 0.999, 0.711, f, 0.75, -30, 0, NACA64.1.412.afl
38,40,39,41,36,34,37,35, 0.555, 0.751, 0.509, 0.999, 0.752, 0.751, 0.752, 0.999, b, 0.75, -24, 24, NACA64.1.412.afl
;rudder
101,107,102,108,103,109,104,110, 0.017, 0.746, 0.087, 0.492, 0.262, 0.746, 0.204, 0.492, r, 0.56, -35, 35, NACA0009.afl
99,101,100,102,105,103,106,104, 0.017, 0.999, 0.132, 0.747, 0.262, 0.999, 0.253, 0.747, n, 1.0, 0, 0, NACA0009.afl
;elevators
144,154,146,155,142,152,105,153, 0.763, 0.457, 0.840, 0.244, 0.999, 0.457, 0.983, 0.244, e, 0.64, -33, 33, NACA0009.afl
145,144,147,146,143,142,106,105, 0.756, 0.999, 0.764, 0.933, 0.999, 0.999, 0.999, 0.933, n, 1.0, 0, 0, NACA0009.afl
150,145,151,147,148,143,149,106, 0.840, 0.244, 0.763, 0.457, 0.983, 0.244, 0.999, 0.457, e, 0.64, -33, 33, NACA0009.afl

Turboprops

The turboprops section defines the turboprop engines, and makes the truck a plane! It is important that this section comes AFTER the props section, becauses it will use props (as in accessories) elements to make props (as in propeller) (does this even make sense?). The props elements used by the turboprop are four pale.mesh (propeller blades) and one spinprop.mesh (translucent rotating disc), all having the same reference node as the turboprop. Easy, eh? Notice that currently turboprop have always 4 blades. Each prop blade is associated to a blade tip node, and you must ensure the blade nodes are correctly interconnected with beams so it will spin freely around its axis, while maintaining a rigid prop disc. See how the Antonov is made. Parameters are:

Reference node number (center of the prop)
Prop axis node number (back of the prop)
Blade 1 tip node number
Blade 2 tip node number
Blade 3 tip node number
Blade 4 tip node number
Power of the turbine (in kW)
Airfoil of the blades

turboprops
122,173,174,175,176,177, 3000.0, Clark-Y.afl
113,168,169,170,171,172, 3000.0, Clark-Y.afl
116,158,159,160,161,162, 3000.0, Clark-Y.afl
119,163,164,165,166,167, 3000.0, Clark-Y.afl

End

The file MUST TERMINATE by end or it will crash

end